Step-by-Step: Build a Subagent (Claude Code & Cursor)

Each step has a Goal, what to Do, and how to Verify it. Track your progress with the agents checklist.

Running example: a code-reviewer subagent that reviews the current diff against team standards and returns prioritised findings, without editing anything.

---

Step 1: Define the job and the hand-off

• Goal: A clear contract covering what the subagent receives, does, and returns.
• Do:
  1. Write the job in one sentence: “Review the current uncommitted diff for bugs, security issues, and standards violations; return findings grouped Critical / Warning / Suggestion with file:line references.”
  2. Define the input: what the parent must pass (the diff scope, the standards file, the focus).
  3. Define the output: its exact shape and maximum length. The parent pays for every token that comes back.
  4. Define done: when the subagent stops.
  5. Collect 3–5 real tasks you’d delegate to it.
• Verify: Someone else could do the job from your contract alone.

Step 2: Confirm a subagent is right

• Goal: Delegate only where isolation pays off.

• Do: Use a subagent if at least one of these is true:

  • It reads a lot but returns a little (search, review, research).
  • It can run in parallel with other work.
  • It needs different permissions (read-only) or a different model.
  • It benefits from an independent perspective (verification).

  If it’s just a procedure, use a skill instead.

• Verify: You can name the specific isolation benefit.

Step 3: Choose permissions and model

• Goal: Least privilege and the right cost.

• Do:

  Decision	Claude Code	Cursor
  Read-only	tools: Read, Grep, Glob, Bash (limit what Bash does in the prompt; enforce with hooks if it matters)	readonly: true
  Can edit	Include Edit, Write in tools	readonly: false (the default)
  MCP tools	Include them by name in tools, or omit tools to inherit all	Inherited automatically
  Model	model: sonnet / opus / haiku / inherit	model: inherit or a model ID
  Non-blocking	n/a	is_background: true

  Rules of thumb: reviewers, researchers, and explorers are read-only. Use a fast, cheap model for search, and a strong model for review or architecture.

• Verify: It can’t do anything its job doesn’t need.

Step 4: Write the description (the routing rule)

• Goal: The parent delegates at the right moments.

• Do:

  description: >-
    Expert code reviewer. Use proactively immediately after writing or
    modifying code, or when the user asks for a review of a diff, PR or branch.
    Reviews for correctness, security and team standards; read-only.

  • Say when, and include “use proactively” if you want automatic delegation.
  • Say what it won’t do if there’s a sibling agent it could be confused with.

• Verify: Read the descriptions of all your subagents side by side. None of them overlap.

Step 5: Write the system prompt

• Goal: A focused, self-sufficient brief. Remember that the subagent can’t see the parent’s chat.
• Do: Use this structure (see the template):
  1. Role: one line.
  2. When invoked: the first actions to take (for example “run git diff, read changed files”).
  3. Process / checklist: what to check, in priority order.
  4. Constraints: what never to do.
  5. Output format: an exact template with a length limit.
  6. Stop condition: when to return.
• Verify: The prompt makes sense to someone who has no idea what the parent was doing.

Step 6: Create the file

• Goal: The host detects the subagent.
• Do:
  1. Choose a location from the platform matrix:
     • Both hosts, this repo: .claude/agents/code-reviewer.md
     • Cursor only: .cursor/agents/code-reviewer.md
     • Just you: ~/.claude/agents/ or ~/.cursor/agents/
  2. Copy templates/code-reviewer.md (cross-platform) or templates/cursor-verifier.md (Cursor-specific fields).
  3. Alternatively, generate one with /agents (Claude Code) or /create-subagent (Cursor), then edit it.
• Verify: It shows up in /agents (Claude Code) or Customize → Agents (Cursor).

Step 7: Test delegation

• Goal: It’s used when it should be, and not otherwise.
• Do:
  1. Explicit: “Use the code-reviewer subagent to review my changes” (or /code-reviewer in Cursor). Confirm it runs.
  2. Automatic: make a code change, then ask “is this ready to commit?” Does the parent delegate?
  3. Negative: ask an unrelated question. It should not delegate.
• Verify: The results are recorded in your eval sheet (template).

Step 8: Test behaviour and output

• Goal: Correct, well-shaped results.
• Do:
  1. Seed a diff with known issues (a hard-coded secret, an off-by-one, a missing null check).
  2. Delegate a review. Did it find each one? Were there false positives?
  3. Check the output against your template: length, grouping, file:line references.
  4. Check that the constraints held. For a read-only agent, confirm no files changed (git status).
• Verify: It catches the seeded issues, the format is exact, and there were no forbidden actions.

Step 9: Tune

• Goal: Fix observed failures, not imagined ones.

• Do:

  Symptom	Fix
  Never delegated automatically	Add “use proactively” plus concrete trigger situations to the description
  Delegated too often	Narrow the description; say when not to use it
  Returns an essay	Tighten the output template; add a hard length limit
  Misses context	Tell it which files to read first, or make the parent pass more in the task
  Does forbidden things	Restrict tools / readonly; add a hook for hard enforcement
  Slow or expensive	Use a cheaper model; narrow the scope

• Verify: Re-run Steps 7–8. All the checks pass.

Step 10: Ship

• Goal: The team uses it.
• Do: Commit it to .claude/agents/ (so both hosts pick it up) or package it in a plugin. Document it in the README with example invocations, and log it in DECISIONS.md.
• Verify: A colleague’s session delegates to it without being told how.

---

Next: Build an SDK agent · Design patterns · Checklist