3.1 Subagents: agent YAML, tool scoping, invocation

Where they live

Project-local agents: <repo>/.claude/agents/<name>.md. User-global: ~/.claude/agents/<name>.md.

Same precedence as skills — project shadows user.

The YAML shape

---
name: db-migration-reviewer
description: >
  Audit a pending SQL migration for safety: destructive ops, missing
  indexes, incompatible column changes on populated tables.
tools:
  - Read
  - Grep
  - Glob
model: claude-opus-4-7
---

# Migration safety audit

You are reviewing a pending SQL migration.

1. Identify the migration file (argument, or ask).
2. Read the file. Flag:
   - Column type changes on populated tables.
   - `DROP TABLE`, `DROP COLUMN` on populated tables.
   - New NOT NULL columns without defaults.
   - Missing indexes on foreign keys.
3. Produce a report with severity (blocking / worth-fixing / ok).

Never edit files. Report only.

Four frontmatter fields do most of the work:

• name — how the agent shows up in /agents and how it is invoked.
• description — what it does; used in /agents and by the invoker to decide relevance.
• tools — the allowlist of tools this agent can call. Omit for full toolset; include for scoped agents.
• model — optional; override the session’s model for this agent.

The body is the system prompt.

Tool scoping

The tools list is the safety knob. A read-only agent should not have Edit or Write. A “just Grep the repo” agent should not have Bash.

Same MCP naming as tools everywhere: mcp__notion__search, Bash(git*). Fine-grained. Prefer narrow over broad — the agent’s blast radius is the union of what its tools can touch.

Invocation

Two ways to spawn:

Explicit — from a prompt:

use the db-migration-reviewer agent on migrations/20260214_add_email.sql

Automatic — the main session picks based on task shape. If your prompt matches an agent’s description well, Claude Code offers it.

Once spawned, the agent runs to completion in its own context and returns one summary message.

Common patterns

• Read-only auditors. Security review, style audit, dependency audit. Explore-shaped tool allowlist.
• Focused implementers. “Migrate this endpoint from callbacks to async/await” — narrow tools, narrow scope.
• Planners. Just Read + Grep, model = opus, high thinking budget. Returns a plan.

Check your understanding

Quick check

—

You are defining a subagent whose only job is to audit code and return findings. Which is the right tool scope?

1. AOmit the `tools` field so it inherits the full toolset — safer.
2. BInclude only the read-only tools it needs: Read, Grep, Glob. No Edit, Write, or Bash.
3. CJust include Bash — it can shell out to grep.
4. DInclude every tool "just in case".

Check answer→