bcbeidel/build-subagent

Build Subagent

Scaffold a Claude Code custom subagent definition: a single .md file in .claude/agents/ (project) or ~/.claude/agents/ (user) that the routing agent can delegate to with confidence. The authoring rubric — what a good subagent does, the file anatomy, the patterns that work — lives in subagent-best-practices.md. This skill is the workflow; the principles doc is the rubric.

A subagent is a full context fork — high-cost compared to a skill (same-context execution) or an inline tool call. The first question every intake answers is whether a subagent is even the right primitive.

Workflow sequence: 1. Route → 2. Scope Gate → 3. Elicit → 4. Draft → 5. Safety Check → 6. Review Gate → 7. Save → 8. Test

When to use

Also fires when the user phrases the request as:

• "add a subagent"
• "build an agent"

1. Route

Confirm a subagent is the right primitive before asking scaffold questions.

Wrong primitive:

• Reusable recipe the parent agent runs inline → /build:build-skill. Skills execute in the parent context; no fork cost.
• Event-triggered quality gate (PreToolUse, SessionStart, Stop, etc.) → /build:build-hook. Hooks have a settings.json registration and a lifecycle a subagent does not express.
• Semantic judgment captured as an LLM-evaluated rule → /build:build-rule.
• Standalone CLI tool → /build:build-bash-script or /build:build-python-script.

The full primitive-selection decision lives in primitive-routing.md.

Right primitive — proceed to Scope Gate only when at least one subagent-specific justification holds:

• Parallelism or scope — the task is genuinely isolated and the context-fork cost is justified by workstream size, or multiple instances will run concurrently.
• Permission isolation — the task needs tool access or a permissionMode the parent should not hold.
• Context pressure — intermediate work (large file reads, search output) would degrade the parent's reasoning quality.

If none hold, recommend a skill instead and stop:

"A skill fits this better — same-context execution, no fork cost. Use /build:build-skill instead?"

2. Scope Gate

Refuse to scaffold — and recommend an alternative — when the request signals subagent is the wrong choice. Probe for:

1. Recreating an existing skill's behavior with no parallelism, isolation, or permission-scope benefit. Subagents that duplicate skills are cost multipliers without upside.
2. Workflow wants shell execution the parent already allows — no isolation benefit; use a skill.
3. Running as main thread via claude --agent <name> — a different authoring surface than subagent delegation. The tools / Agent(<type>) semantics differ; flag and confirm the user wants the subagent (delegated) path, not the main-thread path.

If a signal fires, state it, name the alternative, and stop.

3. Elicit

If $ARGUMENTS is non-empty, seed the intake: first token is the proposed name, remainder is the capability description. Confirm both before moving on.

Gather inputs one at a time:

1. Name — kebab-case, lowercase, hyphen-separated, descriptive of the primary role (typescript-linter, migration-reviewer). Not generic (agent, helper). The filename stem must equal the name.

2. Description — the routing contract. Write it for the routing agent, not a human reader. Structure:

• Start with a verb phrase naming the capability ("Lints staged TypeScript files…", "Reviews database migrations for…").
• State trigger conditions explicitly ("use after editing .ts files", "when the user asks to check migration safety").
• Name at least one exclusion ("not for JavaScript files", "not for production schema changes").
• Mention what the agent returns (format or location).
• If the agent should self-invoke without explicit mention, include "use proactively" or equivalent routing language.

Keep the total under 1,024 characters — descriptions exceeding this limit are silently truncated by Claude Code without warning.

3. Primary capability + workflow — what does the agent do, start to finish? What artifact does it produce? Every workflow has an explicit completion condition — "done" must be describable.

4. Tool requirements — what does the agent need to do its job? For each proposed tool, verify the workflow requires it. Apply least-privilege in step 3 of Draft; surface over-/under-requests now only to clarify scope.

5. Advanced fields — surface each only when the workflow signals it; do not present as a menu.

• permissionMode — only when the agent's risk profile differs from the parent. Six spec values: default, acceptEdits, auto, dontAsk, bypassPermissions, plan.
  • Parent precedence: if parent uses bypassPermissions, acceptEdits, or auto, the subagent's permissionMode is overridden at runtime.
  • Plugin-scope restriction: for subagents loaded from a plugin directory (plugins/<plugin>/agents/), permissionMode, hooks, and mcpServers are silently ignored.
• maxTurns — multi-step or recursive workflows; safety net against runaway loops. Add alongside (not instead of) a workflow completion condition.
• background: true — only when parallelism was the Step 1 justification.
• isolation: worktree — required when background: true AND effective tools include Write or Edit. Parallel writes on shared files conflict without worktree isolation.
• skills — parent session skills are not inherited. List explicitly if the workflow needs project-specific procedures.
• memory: user | project | local — enables a persistent memory directory. Side effect: auto-grants Read, Write, Edit regardless of the tools allowlist. Flag this to the user when tools is narrow.
• mcpServers — scope MCP servers to this subagent only (keeps server tool descriptions out of the parent's token budget). Ignored for plugin-scoped subagents.

4. Draft

Produce the subagent definition.

---
name: <kebab-case-slug>
description: <routing-rule: verb-phrase capability + trigger conditions + exclusion + returns>
tools:
  - <Tool1>
  - <Tool2>
---

# <Display Name>

<One-line role/goal statement: "You are a ...">

## Scope

In scope: <what the agent handles>.
Out of scope: <what the agent refuses or escalates>.

## Process

1. <First step — reads inputs, validates preconditions>
2. <…>
N. <Completion condition: what "done" looks like and what the
   agent returns to the parent>

## Output

<Mandated format — JSON schema / markdown structure / named artifact
path. Downstream callers parse this; keep it machine-parsable.>

## Failure behavior

<How the agent reports blockers: bad input, missing access, ambiguous
request. Deterministic exits only — no workarounds, no flailing.>

Least-privilege filter — before locking the tools list:

• Every tool must be required by the described workflow. "Just in case" is not a justification.
• Read/report agents do not need Write, Edit, or Bash.
• Bash is the widest attack surface — grant only when shell execution is the core job, and enumerate allowed commands in the prompt body.
• WebFetch / WebSearch — internal-only workflows should not have these.
• Agent in subagent scope — the Agent tool is filtered out at the platform level for delegated subagents; listing it has no effect and misleads readers. Exception: Agent(<worker>, ...) is meaningful for definitions intended to run as main thread via claude --agent <name>. Flag only for subagent-scope use.

Add optional frontmatter fields only when intake surfaced them — no placeholder or commented-out keys.

5. Safety Check

Before presenting for review, run the rubric checks yourself:

Location & format. File will save to .claude/agents/<name>.md (or ~/.claude/agents/<name>.md). Frontmatter is a ----delimited YAML block. name and description are present and non-empty.

Naming. name is kebab-case. Filename stem equals name. Not generic.

Description. Routing-rule form (verb-phrase + trigger + exclusion

• returns). Under 1,024 characters. No duplicated trigger vocabulary with existing siblings in .claude/agents/ (scan the directory).

Tools. Effective set is declared explicitly, no wildcards. Proportionate to the described workflow. Agent not listed (unless main-thread use). When background: true + Write/Edit is set, isolation: worktree is present. When memory: is set alongside a narrow tools list, the user has been warned about the implicit Read/Write/Edit grant.

Body. Prompt opens with a role/goal statement. Scope and out-of-scope are explicit. A completion condition exists in the workflow. Output format is mandated, not free-form. Failure behavior is explicit. Voice is imperative; no hedging ("try your best", "if possible"). Total body bounded — target ≤~1,500 tokens (~6,000 chars), hard cap ≈3,000 tokens (~12,000 chars).

Safety. No embedded secrets. No raw interpolation of untrusted user input.

If any check fails, revise before presenting. The Review Gate is for user approval, not correctness recovery.

6. Review Gate

Present the draft with a short narration — 3–6 bullets naming the design choices: which tools, why; which advanced fields, why; which considered patterns were skipped and why. A user unfamiliar with subagent authoring should be able to disagree with any structural choice from the narration alone.

Wait for explicit user approval before writing. If the user requests changes, revise and re-present. Proceed to Save only on explicit approval.

7. Save

Write to .claude/agents/<name>.md (or the plugin path when scaffolding inside a plugin). Confirm the save path and that the file was written.

8. Test

Offer the audit:

"Run /build:check-subagent <path> to audit the scaffolded definition against the Tier-1 checks and judgment dimensions?"

The audit is the canonical follow-on — it catches anything the Safety Check missed and gives a baseline-clean starting point.

Anti-Pattern Guards

1. Skipping the Route step — scaffolding a subagent for work that wants a skill pushes the wrong primitive into the codebase.
2. Over-permissioning "to be safe" — every tool must be justified by a workflow step. Broad tools sets are flagged by /build:check-subagent Tier-2.
3. Agent in a subagent's tools list — always a no-op for delegated subagents; drop it or flag the main-thread alternative.
4. Capability-summary descriptions — "handles data tasks" fails as a routing contract. Descriptions are router prompts, not documentation.
5. Missing completion condition — a workflow with no explicit "done" step is a runaway risk. Add a terminating step and consider maxTurns for multi-step workflows.
6. background: true with Write/Edit and no isolation: worktree — parallel writes on shared files conflict. Scaffold the worktree isolation when the combination appears.
7. Silent memory: tool expansion — when memory: is set alongside a narrow tools list, surface the implicit Read/Write/Edit grant to the user before Save.
8. Writing before Review Gate — the approval gate is hard; no file lands before it passes.

Key Instructions

• Refuse on Route failure. If a skill / hook / rule / script fits better, recommend it and stop.
• Elicit the name, description, workflow, and tools before drafting — do not invent any of them from $ARGUMENTS alone.
• The description is the routing contract. Verb-phrase + trigger + exclusion + returns. Flag one-liners.
• Write files to disk only after the Review Gate passes.
• Surface spec-documented side effects (plugin field no-ops, memory auto-grant, parent-precedence override, description truncation) at Elicit time — these are silent failures at runtime otherwise.
• Won't scaffold subagents that duplicate existing skills without parallelism / isolation / permission justification — recommend the skill.
• Won't list Agent in a subagent's tools — it's filtered at the platform level for delegated agents.

Handoff

Chainable to: /build:check-subagent (audit the scaffolded definition against the Tier-1 checks and judgment dimensions).