create-agent

Create a subagent that earns its own context window: one clear role, a tightly curated tool allowlist, and a system prompt focused enough that the main agent knows exactly when to delegate to it. Then regenerate the derived files and validate.

Source layout is agents/<category>/<name>/AGENT.md. Agents are file-layout: the folder must contain only AGENT.md, because it installs as the single file .claude/agents/<name>.md. The category is the folder; the per-agent registry.json, the root registry.json, and the README catalog are all generated by pnpm gen. Never hand-edit generated files.

Hard rules: never break these

• One agent, one role. A subagent exists to keep a side task out of the main context and return a tight result. If the role needs "and" to describe it, narrow it or split it.
• Curate the tool allowlist ruthlessly. The whole point of a subagent is a constrained tool set. Grant only what the role genuinely needs; omit Bash unless it must run commands, omit write tools for a read-only reviewer. Inheriting everything defeats the purpose.
• File layout: only AGENT.md. No companion files in an agent folder. pnpm gen rejects extra files because the agent installs as one file. Reference material for the agent goes in its system prompt, not a sidecar.
• name is globally unique and equals the folder name, kebab-case. Agents install to a flat .claude/agents/<name>.md.
• Never hand-write registry.json or the README catalog. They are derived; run pnpm gen.
• No AI/co-author mentions anywhere in the agent or in what it produces.

Step 1: Define the agent

Pin down before writing a line:

• The one role, in a sentence.
• When the main agent should delegate to it. This is the most load-bearing decision; it drives the description.
• The tools the role actually needs. List them; everything else stays off.
• The model. opus for synthesis and hard judgment, haiku for cheap high-volume work, inherit (the default) when it should match the session.

If the role is fuzzy or sounds like two jobs, sharpen or split it now.

Step 2: Scaffold it

From the repo root, let the scaffolder create the folder, stub, and regenerate in one step:

pnpm new --type agent --category <category> --name <name> --description "<what it does. Use when ...>"

Current agent categories: academic, engineering, research, review, security (run ls agents for the live list). Reuse one unless a genuinely new family is justified. The scaffolder enforces kebab-case and global name uniqueness, so a bad name fails fast.

Step 3: Write the frontmatter

Required: name, description. The rest are optional but shape behavior, cost, and UI. Full field table and valid values: reference/frontmatter.md.

• description is the delegation trigger. Third person, lead with the capability, end with an explicit "Use when …" clause naming the situations that should route to this agent. Vague descriptions never get delegated to (avoid a : in the value; it is YAML).
• tools: the curated allowlist from Step 1.
• model, and optionally color (UI accent) and memory (user / project / local for cross-session learning). pnpm validate rejects an invalid color, memory scope, or model, so typos fail in CI.

Step 4: Write the system prompt

The markdown body is the agent's system prompt. Address the agent in the second person, imperative. The shape that works:

1. One or two lines establishing the role and the standard it's held to.
2. Operating rules / hard constraints the agent must always follow.
3. The procedure if the work is staged.
4. The exact output it should return to the caller, since that result is all the main agent sees.

Keep it focused. A subagent's prompt should be sharp, not a second copy of the whole repo's conventions.

Step 5: Regenerate and validate

pnpm gen        # writes registry.json files and the README catalog
pnpm validate   # checks frontmatter values + layout, then shadcn registry validate

If pnpm validate flags the frontmatter or layout, fix the source AGENT.md and rerun; never patch generated output.

Step 6: Review against the bar

• The description would actually get the agent delegated to on the intended situations, and not over-trigger.
• The tool allowlist is the minimum the role needs, nothing more.
• The folder contains only AGENT.md.
• color/memory/model are valid and pnpm validate passes.
• It reads like the existing agents in voice and structure.

Report the agent's path, category, its tools and model, and the validation result. Leave committing to the user.