Install crew

Install the crew

This skill turns a set of generic agent templates into a customised team of agents for the person installing it — wired to their org, their house style, their tools.

The team is one shape, instantiated to fit anyone:

                    chief-of-staff            ← orchestrator: triages, routes, synthesises
        ┌───────────────┼───────────────┐
     lead A           lead B           lead C  ← one "lead" per division (see below)
        └───────────────┼───────────────┘
                 (any lead pulls in any specialist)
   architect · code-auditor · program-manager · problem-solver
   presentation-writer · voice-scriptwriter · growth-marketer
   product-designer · ops-steward · content-engine
   web-builder · video-editor · skool-writer-and-publish      ← shared specialists
   inbox-reader · email-writer · notes-archivist · memory-harvester  ← opt-in comms

A "division" is deliberately abstract. For the installing user it might be a business, a department, a team, a product line, a client portfolio, or a person they manage. The installer's job is to learn what their divisions are and generate one lead per division.

Your job when this skill runs: conduct a short interview (informed by anything already in their config), confirm a plan, then write the agent files. Never invent the user's business facts — ask, or leave a clean placeholder and say so.

---

Files in this skill

• templates/orchestrator.md — the chief-of-staff template.
• templates/division-lead.md — ONE lead template, instantiated once per division.
• templates/specialists/*.md — the 13 generic specialists.
• templates/comms/*.md — the 4 integration-dependent agents (opt-in).
• references/rendering-claude-code.md — how to write Claude Code subagents.
• references/rendering-codex.md — how to write Codex prompts + AGENTS.md.
• references/team-readme-template.md — the team README the installer writes for the user.

Read the relevant rendering reference before you write files. Read each template before you fill it.

---

Step 0 — Confirm the target tool(s)

Ask which the user runs (offer both):

• Claude Code → render native subagents (references/rendering-claude-code.md).
• Codex → render native custom-agent TOML files + a root AGENTS.md (references/rendering-codex.md). Current Codex releases can spawn project or global custom agents. Detect the installed Codex version before rendering and use the legacy prompt-file fallback in that reference only for an older release without custom agents.
• Both → render each from the same answers.

Step 1 — Read before you ask

Look for context the user has already written, and use it to propose a draft org rather than interrogating them from scratch:

1. Global config: ~/.claude/CLAUDE.md (and ~/.codex/AGENTS.md if present).
2. Project config in the current working directory: CLAUDE.md and/or AGENTS.md.

From whatever exists, extract candidate divisions (named businesses, departments, teams, products), the user's house style (language/spelling variant, emoji policy, versioning rules), a default tech stack if mentioned, and any filing conventions. Draft a proposed roster from this. If nothing is found, start clean.

"I read your config and it looks like you run A, B, and C — should each be its own lead? Anything missing?" beats twenty cold questions.

Step 2 — Interview (confirm and fill the gaps)

Work through these, conversationally, confirming what you inferred in Step 1. Prefer multiple-choice where you can. Keep it tight.

1. Divisions → the list of leads. For each: a display name, the domain it owns, a one-line "what it is", what it owns, what it explicitly does not own, the standing facts it must always know, and who it hands off to. A division can be a company, a department, a product, a client book, or a report you manage. (If the user has only one domain, one lead is fine — the orchestrator still adds value.)

2. Specialists → which of the 13 to include (default: all). Drop any that don't fit how they work.

3. Comms agents (opt-in, default off) → inbox-reader, email-writer, notes-archivist, memory-harvester. Only install the ones the user wants, and for each, capture what integration they'll wire (or note it's unwired).

4. House style → spelling/language variant, emoji policy, deliverable versioning, any standing "always do X" rules. This becomes {{WORKSPACE_CONTEXT}}. Do not assume a variant or an emoji rule — use what they tell you; if they say nothing, render a neutral block.

5. Default tech stack (if they build software) → fills the architect's {{DEFAULT_STACK}}.

6. Filing map (if they want ops-steward) → where things get filed; fills {{FILING_MAP}}.

7. Install scope → project (<workspace>/.claude/agents/) or global (~/.claude/agents/). See the non-git caveat in the rendering reference and pick accordingly.

8. Front door (recommended: yes) → should the orchestrator become the DEFAULT session, so a bare claude (and the desktop app) boots straight into it with no flags? If yes, you'll set the agent key in Step 4.5.

   Before asking this question, scan for scheduled headless runs — the agent key applies to claude -p too, so an unattended job would silently start booting as the orchestrator. Check and SHOW the user what you find:

   crontab -l 2>/dev/null | grep -n "claude"
   grep -rln "claude -p\|claude --print" ~/Library/LaunchAgents /Library/LaunchAgents 2>/dev/null
   grep -rln "claude -p\|claude --print" <workspace> --include="*.sh" 2>/dev/null
   

   (On Linux, check systemd user timers and /etc/cron* as well.) Any hit that should NOT run as the orchestrator must pin its own agent with --agent <name> — offer to add the flag for them before enabling the front door. Most people with a cron do not remember they have a cron; the scan is the point, not the caveat.

Step 3 — Show the plan, then confirm

Before writing anything, show the user:

• The exact list of agents you'll create (orchestrator + each named lead + chosen specialists + any comms agents).
• The target tool(s) and the exact directory(ies) you'll write to.
• A one-line note on scope and (if relevant) the non-git caveat decision.

Wait for a yes. This is the only gate — once confirmed, write everything.

Step 4 — Render and write

Follow the rendering reference for each target tool. The mechanics:

1. For each division, copy templates/division-lead.md and fill its tokens ({{LEAD_NAME}}, {{LEAD_SLUG}}, {{DOMAIN}}, {{WHAT_IT_IS}}, {{OWNS}}, {{DOES_NOT_OWN}}, {{KEY_FACTS}}, {{HANDOFFS}}, {{LEAD_COLOR}}). Give each a unique kebab-case name (e.g. lead-<slug>).
2. Copy each chosen specialist; fill {{DEFAULT_STACK}} (architect) and {{FILING_MAP}} (ops-steward) where present.
3. Copy each opted-in comms agent; fill {{INTEGRATION_SETUP}}.
4. Inject the same rendered {{WORKSPACE_CONTEXT}} block into every agent so the whole crew behaves consistently.
5. Copy templates/orchestrator.md and regenerate {{LEADS_LIST}} and {{SPECIALISTS_LIST}} from the roster you actually installed — not the full catalogue.
6. Write the team README from references/team-readme-template.md, filling {{ROSTER_TABLE}} from the installed files.
7. Grep every written file for a leftover {{ — a surviving token is a bug; fix it before finishing.

Step 4.5 — Make it the front door (if opted in)

If the user said yes to the front-door question, wire the orchestrator in as the default main-loop agent (Claude Code only):

1. Set the agent key in the chosen scope's settings — ~/.claude/settings.json for global installs, <workspace>/.claude/settings.json for project installs:

   { "agent": "chief-of-staff" }
   

   Merge into the existing file — never overwrite other settings. This swaps the main loop to the orchestrator (its system prompt, tools, and model) for bare claude and the desktop app, and --agent <name> still overrides it per-invocation when the user wants a different seat.
2. VS Code extension caveat — the extension has no agent setting of its own. If the embedded session doesn't pick up the key, the integrated terminal is the route. Offer this shell function (NOT a bare alias — that breaks claude update and claude --version):

   claude() {
     if [[ $# -eq 0 ]] || [[ "$1" == -* ]]; then
       command claude --agent chief-of-staff "$@"
     else
       command claude "$@"
     fi
   }
   

3. Headless caveat — the agent key DOES apply to headless claude -p runs (verified empirically 2026-08-18). Warn the user: any unattended script that should NOT run as the orchestrator (crons, render jobs, pipelines) must pin its own agent explicitly with --agent <name>, or it will silently boot the orchestrator — its persona, tools, and model — for every scheduled run. Revisit the scheduled-run scan from the Step 2 front-door question: every hit found there must be pinned (or the user must explicitly accept the change) BEFORE you set the key. Nothing errors when this goes wrong — the job just quietly becomes a different job — so the scan is the only warning they get.

Step 5 — Report and tell them to restart

Report what you wrote and where. Then:

• Claude Code: agents load at session start, not mid-session — tell the user to start a new session, then invoke @chief-of-staff for anything cross-cutting or call any agent by name.
• Codex: point them at the new prompt files and AGENTS.md.
• If you mirrored project files to global (non-git workspace), remind them to re-sync after edits.

Step 6 — First drive (do not skip)

An installed crew a user doesn't know how to drive is a failed install. After they restart, walk them through three checks in their new session, in order:

1. Identity check: have them ask "who am I speaking to?" — the orchestrator should answer in character (and, if a sign-off was configured, close with it). If not, the agent didn't load: re-check the install directory and restart. If they opted into the front door (Step 4.5), a BARE claude must pass this check with no flags.
2. Inline answer: one trivial question from their real work — it should be answered directly, with no delegation. This teaches them the inline-first gate.
3. First delegation: one small real task that clearly belongs to a single lead ("ask the <lead> to…"). Point out the routing line and the synthesised answer.

Then leave them a QUICKSTART.md next to the team README covering: when to talk to the orchestrator vs a lead directly; that delegation is the exception (inline-first); how to ask for a nested sub-team when work is genuinely big; the sign-off-stops = context-getting-full canary and compacting around 40%; and where the roster README lives. Close by telling them the update path: pull the kit's latest and re-run update-crew. If they installed by hand-copying the templates rather than via the marketplace/plugin, the update path is different — clone or pull the kit's repo and run update-crew from there against their installed agents (see "Hand-copied installs" in the update-crew skill).

---

Guardrails

• Never fabricate the user's facts. If you don't know a division's details, ask, or write a clear placeholder and tell them to fill it. A confidently-wrong fact is worse than a gap.
• Keep the published descriptions clean. Real names, companies, domains, and paths belong in the persona body via {{WORKSPACE_CONTEXT}}, never in the frontmatter description (that string is broadly visible).
• Scale the crew to the user. One division and three specialists is a perfectly good crew. Don't push all 18 agents on someone who needs five.
• Hold the boundaries. The value of this team is clean ownership and routing — keep each lead's "does not own" honest so the orchestrator can route without collisions.