Index of every page on this site: llms.txt
All skills
Run it yourself

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`.

  • 1 file
  • 20.4 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/onboard-ai-agent

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈158 tokens for metadata: the name and description. ≈5.1k when used: this file.

Description uses 7.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈630 characters, or 7.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 7f168b8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for colaberryintern/colaberryenterprise_ai_leadershipaccelerator/onboard-ai-agent