---
name: onboard-ai-agent
description: Build or migrate ONE AI agent to Reese's real standard — a full AI employee with identity, accountability, trust instrumentation, and governance, not just an AGENT_REGISTRY entry with a name. Covers the real registry declarations, the identity/accountability seed, risk-tier and autonomy classification, and the three bespoke code chokepoints (authorization, activity logging, ticket visibility) every agent's business logic must call. Invoke when Ali says "onboard a new agent", "build the next AI employee", "migrate X to the Reese process", or is standing up or hardening any agent in `agentRegistrySeed.ts`.
title: onboard-ai-agent
canonical_url: https://skilld.dev/gh/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/onboard-ai-agent
last_updated: 2026-10-08T09:39:34.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install colaberryintern/colaberryenterprise_ai_leadershipaccelerator/onboard-ai-agent`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/onboard-ai-agent`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/onboard-ai-agent) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/onboard-ai-agent`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/onboard-ai-agent --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/onboard-ai-agent --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# onboard-ai-agent — bring one agent to Reese's real standard

Ali, 2026-09-14, after the fleet-wide autonomy-classification dry-run found 232
registered agents and exactly one (Reese) with a real `system_prompt`/`persona_version`:
"Those other agents aren't registered like Reese. Reese should represent the new
registration process and I will pull the other agents over to this process one at a
time... The agents will be actual AI employees so they will be much more than just a one
trick poney. They will be robust like Reese and report to an actual human that will be
responsible for them." And the follow-up that authored this skill: "Make sure in this
new skill process runs the autonomy classifier and has everything that reese has because
when I create new agents I want them to fill out all functionality every time and if
unsure to ask... I don't want to have to fill in the gaps later."

**This is a checklist, not a script.** Ali runs it himself, one agent at a time, at his
own pace — there is no batch migration here, and this skill does not attempt one.

---

## What this produces

Not a row in `AGENT_REGISTRY` with a name. A real AI employee: a durable identity a
human or student can actually talk to, a named human who is accountable for it, an
honest risk tier and autonomy level derived from what it can really do, and full trust
instrumentation (audit trail, cost tracking, ticket visibility) so its work is as
inspectable as a human employee's. Everything below exists because Reese has it and the
other 231 registered agents mostly don't.

---

## Obligations — one row per thing a real agent needs

Tier A rows are free — any row in `ai_agents` gets them with zero extra code. Tier B
rows are deliberate config/data declarations. Tier C rows require real code the agent's
own business logic must call; nothing does this automatically.

| # | Tier | Obligation | Where | What happens if you skip it |
|---|---|---|---|---|
| 1 | A | Agent Detail page (Overview, Talk, Decisions, Goals, Reports, Memory, Directives, Charter tabs) | `backend/src/services/reese/agentDetailService.ts` `getAgentDetail()` — generic, works for any `ai_agents` row | Nothing to skip — this renders for every registered agent automatically. |
| 2 | A | Talk tab (live chat with the agent) | `backend/src/services/reese/agentManagerConversationPrompt.ts` — agent-agnostic, injects the agent's own real system_prompt/directives/memory/recent activity | Nothing to skip — but a blank/generic `system_prompt` (see #4) makes the conversation hollow even though the tab renders. |
| 3 | A | Standing Directives, Goals & 1:1s, Report Subscriptions, Memory Proposals | Same generic Agent Detail surfaces | Nothing to skip — free for any row. |
| 4 | B | A real `AGENT_REGISTRY` entry with `agent_type`, `module`, `source_file`, `trigger_type`, `schedule`, `category`, `description`, **`tools_granted`, `system_prompt`, `persona_version`** | `backend/src/services/agentRegistrySeed.ts` — Reese's entry (`agent_name: 'Reese'`) is the worked example; `PreviewStackReaper`/`StaleActionRecovery` show the bare-minimum "before" shape most of the fleet is still in | Without `tools_granted`: the autonomy classifier (#8) has nothing to classify and the agent defaults to `observe`, honestly but uninformatively. Without `system_prompt`: the Talk tab (#2) and any real conversation loop have nothing to run on — Reese is the ONLY entry in the 252-agent registry with `system_prompt` or `persona_version` set today. |
| 5 | B | Identity + accountability: an `AdminUser` + `Enrollment` + `CommunityMember` the agent can act as, plus `reports_to_type`/`reports_to_id` pointing at a real human or AI Leadership agent | `backend/src/services/agentBlueprint/agentIdentitySeed.ts` `seedAgentIdentity()` — real and generic, already reused by 5 other agents (name-display only) via `ticketCreatorIdentitySeed.ts` | No identity: the agent has no durable presence a student or manager can see or address. No `reports_to`: there is no accountable human — this is the single biggest gap between Reese and the other 231 agents, and the one Ali named directly ("report to an actual human that will be responsible for them"). |
| 6 | B | `RISK_TIER` (R0-R4, honest, not copied from Reese) | `backend/src/modules/delivery/deliveryRiskLevels.ts` for the real meaning (R0=read_only, R1=reversible_content, R2=code_change, R3=schema/security/external_side_effect); set as a bare constant the way `reeseAutonomousOutreachService.ts:26` sets `RISK_TIER = 'R3'` | A wrong tier is either dangerous (too low — a real external-side-effect action never gets reviewed) or paralyzing (too high — routine work permanently stuck in an approval queue with no release path, the exact failure mode this session's real-enforcement scoping work found waiting for Reese). **This is a STOP AND ASK gate — see below.** |
| 7 | B | Role Charter content | Generic model, but never auto-populated by any seed path | An agent with no charter looks unfinished forever — nothing flags the absence as blocking, so it's the easiest obligation to silently forget. |
| 8 | B | Autonomy level, auto-classified from `tools_granted` | `backend/src/services/agentCapabilityClassifier.ts` (pure classifier) + `backend/src/services/agentAutonomyReclassificationService.ts` (the ongoing-sync wiring, merged PR #2540, 2026-09-15) + `backend/src/scripts/classifyAiAgentAutonomyLevels.ts` (one-time backfill, `--apply`, only needed for pre-existing agents that predate the wiring) | **Update, 2026-09-21: PR #2540 merged.** `seedAgentRegistry()`'s real create/update loop now calls `classifyNewAgentAutonomyLevel()` for a brand-new agent, or `maybeReclassifyAutonomyLevel()` when an existing agent's `tools_granted` genuinely changes this boot — asymmetric by source, so a real human decision (`autonomy_level_source: 'manual'`) is never silently overwritten. **Declare `tools_granted` honestly and this now just happens** — no manual classifier run needed for a new agent. The backfill script is still the right tool only for a pre-existing agent that has never gone through either path. |
| 9 | C | Authorization/audit chokepoint on **every** real outbound or write action, branching on the real, mode-aware `allowed` field | `backend/src/services/workLedger/agentActionAuthorizationBridge.ts` `authorizeTicketDispatch()` → `backend/src/services/agentAuthorizationService.ts` `authorizeAgentAction()` | **Update, 2026-09-21, from this session's own real-enforcement build**: skipping this call is no longer merely invisible-until-enforcement — real, live per-agent enforcement now exists (see Known Gaps). `authorizeTicketDispatch()`'s result carries TWO fields easy to confuse: `verdict` (mode-INDEPENDENT — "would this be denied," true regardless of enforcement) and `allowed` (mode-AWARE — unconditionally `true` in shadow mode, the real gate once enforcement is on for that agent). **Branch on `allowed`, never `verdict`/`wouldDeny`** — a real design finding from Reese's own build: getting this backwards makes shadow mode silently start holding real actions the moment the code ships. When `allowed` is `false`, return an honest "held" outcome and skip every downstream side effect that would dishonestly record something that never happened (a "last contacted" timestamp, a ledger event). Reese's OUTREACH path is the correct worked example to copy (her reply path now also does this correctly — see Known Gaps, this was the real fix behind PR #2477's now-closed gap). |
| 10 | C | GOALS-score activity logging, success AND failure paths | `backend/src/services/agentBlueprint/agentActivityLogService.ts` `logAgentActivity()` | **Real gotcha**: there is a same-named, unrelated `logAgentActivity` in `aiEventService.ts` that department/admissions agents call instead — calling the wrong one compiles fine and silently produces no real GOALS-score evidence for this agent. Double-check the import path. |
| 11 | C | Real per-call LLM cost tagging (`agent_id` passed to `getInstrumentedOpenAI()`) | Call site inside the agent's own LLM-calling code | Easy to omit — roughly 50 other call sites across this codebase already don't pass it, and Reese's own reply service needed a real, dated bug fix for exactly this omission. Without it, the agent's real spend is invisible in `ai_events`. |
| 12 | C | Ticket/ProofDesk visibility for real work | `backend/src/services/agentBlueprint/agentTicketLinkService.ts` `ensureAgentTicketForRoom` / `logAgentExchangeActivity` — generic and reusable; Reese's own wrapper is a thin pass-through over this | Without it, the agent's real work never shows up on the tickets board — from a manager's view, the agent looks idle even while doing real work. |
| 13 | C | The actual job (LLM conversation loop, signal-detection thresholds, eligibility gates, whatever this agent's real business logic is) | Bespoke, per agent — see Reese's ~20 source files under `backend/src/services/reese/` for the scale of what "a real agent" actually requires | No registration step can hand this out. This is what the agent's developer designs and writes, informed by the real product/business requirement for that specific role — not templated by this skill. |

---

## STOP AND ASK gates

Do not guess on these. Ask Ali and wait for a real answer before writing code:

- **Risk tier (#6)** — what is the worst real-world consequence of this agent's most
  capable action? Ground the answer in `deliveryRiskLevels.ts`'s real R0-R4 definitions,
  not in how it "feels." Getting this wrong in either direction is a real production
  problem (see #6's consequences column).
- **`reports_to` (#5)** — which real human is accountable for this agent? Not a
  placeholder, not "whoever's convenient" — the actual person who will review its work
  and answer for it, per Ali's explicit "report to an actual human that will be
  responsible for them."
- **`category`/department** — where does this agent sit in the org taxonomy? Don't infer
  it from the agent's name alone if it's ambiguous.
- **The real scope of `tools_granted`** — what is this agent genuinely allowed to do?
  This isn't a documentation exercise; it's the direct input to the autonomy classifier
  (#8) and, eventually, real enforcement. Overstating it inflates the autonomy level
  dishonestly; understating it undersells what the agent needs to do its job.
- **Persona / system-prompt content and tone** — for anything the agent will say to a
  real student or manager, the voice is a real editorial decision, not a default.

If any of these is unclear from the conversation or the surrounding code, ask before
proceeding. Filling in a plausible-sounding guess here is exactly the "fill in the gaps
later" outcome Ali asked this skill to prevent.

---

## From a detailed description to the obligations table

Ali, 2026-09-30: "Most of the time building an agent will come from a request of skills
to plug into this system... an agent will be explained in great detail and then we should
be able to map to all the answers in the skill." Most new agents don't start from a blank
form — they start from a real, detailed description of what the agent does and why. This
section is how to turn that description into real answers for the obligations table above,
instead of re-asking every STOP AND ASK gate from zero regardless of how much the
description already said.

Read the description once, fully, before touching any obligation. Then work through these
in order:

1. **`tools_granted` (#4)** — list every real capability the description names, phrased as
   the same kind of snake_case verb strings the real registry already uses (see #4's real
   examples: `respond_to_dm`, `create_agent_tasks`, `detect_stuck_agents`). Don't invent
   capabilities the description doesn't support, and don't under-list ones it clearly does
   — this list is the direct input to the next 2 steps, not decoration.
2. **Autonomy level, derived, not asked** — run the real classifier's own logic by hand
   against the list from step 1: `agentCapabilityClassifier.ts`'s `KEYWORD_TIERS`
   (`send_`/`respond_to_dm`/`_sms`/`_email`/`_call`/`_dm` → `communicate`;
   `create_`/`update_`/`delete_`/`cancel_`/`resolve_`/`flag_`/`auto_execute_`/`auto_repair`/
   `retry_`/`apply_` → `act_audited`; `propose_`/`identify_`/`generate_` → `suggest`;
   `read_`/`detect_`/`query_`/`evaluate_`/`assess_`/`analyze_`/`monitor_`/`scan_` →
   `observe`) — take the MAX tier across every tool, same as the real code does. Once
   `tools_granted` is declared honestly and seeded, obligation #8's real wiring
   (`seedAgentRegistry()` → `classifyNewAgentAutonomyLevel()`) does this automatically on
   boot — this step is for confirming the description supports the level you expect
   *before* seeding, not a substitute for the real classifier.
3. **`RISK_TIER` (#6)** — do not guess a feeling. Take the single MOST CONSEQUENTIAL real
   action `tools_granted` implies and place it on `deliveryRiskLevels.ts`'s real R0-R4
   scale (R0=read_only, R1=reversible_content, R2=code_change, R3=schema/security/
   external_side_effect — any `communicate`-tier tool is, by definition, an external side
   effect and therefore at least R3). If the description's actions span multiple tiers,
   the tier is the HIGHEST one present, same "max across capabilities" principle as step 2
   — a mostly-read-only agent with one real send action is still a communicate/R3 agent,
   not a mostly-observe one with an asterisk.
4. **`category`/department** — the description's own stated domain or team almost always
   answers this directly (e.g. "helps students with curriculum" → student success; "audits
   agent behavior" → platform/governance). Only fall through to STOP AND ASK when the
   description genuinely doesn't say or implies more than one plausible department.
5. **Persona / system-prompt tone** — draft from the description's own stated audience and
   voice cues (who does it talk to, how formal, what it should never say) rather than a
   generic template. This is still an editorial decision Ali should see before it ships to
   real students, not something to silently finalize.
6. **`reports_to` (#5)** — the one field most descriptions genuinely don't answer (who is
   accountable is an organizational decision, not a technical one derivable from what the
   agent does). This stays a hard STOP AND ASK gate regardless of how detailed the
   description is, unless the description explicitly names the accountable human.

**The STOP AND ASK gates above still apply — but only fire on what's still genuinely
ambiguous after this mapping pass, not by default for every field regardless of input
detail.** A rich description that clearly implies `communicate`/R3 and a clear department
doesn't need those 2 questions re-asked; a description that never names an accountable
human still needs #5 asked every time, no matter how detailed the rest of it is.

---

## Known gaps on Reese herself (2026-09-14, updated 2026-09-21) — don't silently copy these

Reese is the reference implementation, not a finished one. Disclosing her real open
gaps here means this skill doesn't launder them into every future agent as if they were
the standard:

- **RESOLVED, 2026-09-21**: her reply path (`reeseReplyService.ts`
  `maybeTriggerReeseReply()`) now calls the authorization chokepoint and genuinely gates
  on `allowed`, not just logs shadow-mode-style — shipped in this session's own Phase 2
  of the real-enforcement build (not via PR #2477, which predates this fix and is now
  superseded/stale — its own shadow-only advisory check was replaced by a real gating
  one; that PR should be closed, not merged, if it's still sitting open).
- **RESOLVED, 2026-09-21**: new-agent autonomy classification IS wired to boot now — PR
  #2540 merged 2026-09-15 (see obligation #8). Declare `tools_granted` and it classifies
  itself; no manual backfill run needed for a new agent.
- **New, real capability as of 2026-09-21, know it exists**: enforcement is no longer
  purely global. `AiAgent.abac_mode_override` (`'shadow' | 'enforce' | null`) lets an
  admin put ONE agent into real enforcement independent of the platform default —
  visible/settable on that agent's own Agent Detail page (Performance & Settings →
  Authority & controls). A new agent inherits the platform default automatically
  (`null` override); nothing to build for this, but its first real enforcement moment
  can now be a deliberate, single-agent decision rather than an all-or-nothing platform
  flip.
- **The GOALS score's zero-activity fallback is inflated, not conservative** —
  `backend/src/services/agentGoalsDimensionsService.ts`: a brand-new agent with zero
  real tracked activity shows governance=5, lexicon=4, availability=2-or-5 (5 if
  `trigger_type==='on_demand'`), solid=5, observability=3. That's a deceptively
  decent-looking score with no real evidence behind it. Don't read a fresh agent's first
  GOALS score as proof of anything, and don't let anyone else assume it is.
- **Role Charter is never auto-populated by any seed path** (obligation #7) — always a
  manual write, always easy to forget since nothing blocks on its absence.

---

## Verification checklist

Run this after building or migrating, before calling the agent done:

1. **Load the agent's real Agent Detail page** — every tab (Overview, Talk, Decisions,
   Goals, Reports, Memory, Directives, Charter) renders without a fabricated or
   unexpectedly blank state where real data should exist.
2. **Have a real exchange on the Talk tab** — confirm the agent responds using its own
   real `system_prompt`/persona, not a generic fallback.
3. **Take one real action through the agent's code**, then confirm a real row appears in
   `ai_agent_activity_logs` under this agent's own id (obligation #10) — not zero rows,
   not a row under the wrong agent.
4. **Confirm cost tagging** — a real `ai_events` row from that same action has
   `agent_id` populated (obligation #11), not null.
5. **Confirm ticket visibility** — a real ticket appears on the tickets board for that
   action (obligation #12).
6. **Confirm `autonomy_level_source` and `reports_to_id` are both non-null** on the
   `ai_agents` row — an agent with either still null is not finished, regardless of how
   complete everything else looks.

A page that "loads fine" is not the same as an agent that passes this checklist. Run it
for real, don't assume it from the code.

---

## Migrating an EXISTING lightweight agent

Most of the fleet already has a bare `AGENT_REGISTRY` row (`agent_type`, `module`,
`source_file`, `trigger_type`, `schedule`, `category`, `description` — the first 7
fields Reese also has). Migrating one of these is the same obligations table above,
reframed as a gap list against what's already there:

1. Read the agent's current registry entry and its real source file — what does its code
   actually do today? That's the ground truth for `tools_granted`, not a guess.
2. Walk obligations #4-13 in order, checking what's already present vs. missing. Most
   lightweight agents are missing everything from #4's `tools_granted`/`system_prompt`
   onward.
3. Apply the same STOP AND ASK gates — a pre-existing agent doesn't get a pass on risk
   tier or `reports_to` just because it's already running.
4. Run the same verification checklist at the end. An agent that's been live for months
   with no real audit trail is not verified just because it hasn't broken anything
   visibly.

---

## Explicitly out of scope

- **Batch or automated migration** of the other ~230 registered agents — Ali is doing
  this himself, one at a time, "until I have a better process." This skill is that
  process; running it repeatedly is his call.
- **Templating the real business logic** (obligation #13) — necessarily different per
  agent, can't be templated honestly.
- **Rewriting `agentToolRegistry.ts`** into a fleet-wide structured tool taxonomy —
  larger, separate work; this skill works with the real free-text `tools_granted` data
  that exists today.
