Claude Code subagent lifecycle: creation, configuration, evaluation, and troubleshooting. Invoke whenever task involves any interaction with Claude Code subagents — designing, debugging, iterating, or deciding when to delegate work to isolated agent contexts.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Claude Code subagent lifecycle: creation, configuration, evaluation, and troubleshooting. Invoke whenever task involves any interaction with Claude Code subagents — designing, debugging, iterating, or deciding when to delegate work to isolated agent contexts.
Subagent Engineering
Manage the full lifecycle of Claude Code subagents: creation, evaluation, iteration, and troubleshooting.
**Subagent prompts are system prompts.** Before creating or improving
a subagent, invoke `prompt-engineering` to load instruction design techniques.
Skill(ai-helpers:prompt-engineering)
Skip only for trivial edits (typos, formatting).
Route to Reference
Full frontmatter field reference — [${CLAUDE_SKILL_DIR}/references/spec.md] All fields with constraints, Agent
tool parameters, built-in agents, permission modes and inheritance, hooks schema, storage locations, SDK
settingSources requirement
Step-by-step creation walkthrough — [${CLAUDE_SKILL_DIR}/references/creation.md] Decision matrix (subagent vs
skill vs team), frontmatter reference, description writing, tool sets, model selection, system prompt structure, 4
agent type templates, validation checklist
Quality scoring and testing — [${CLAUDE_SKILL_DIR}/references/evaluation.md] 5-dimension scoring rubric with
weights, testing protocol (5 levels), benchmarking methodology, continuous monitoring
Improving an existing subagent — [${CLAUDE_SKILL_DIR}/references/iteration.md] Prompt refinement techniques, A/B
testing, version control, redesign criteria, description optimization
---
name: my-agent
description: What it does. When to use it.
tools: Read, Grep, Glob
model: sonnet
---
You are a [role]. When invoked:
1. [First step]
2. [Second step]
3. [Final output format]
Scope Priority (highest to lowest)
Managed settings (organization-wide)
--agents CLI flag (session only)
.claude/agents/ (project)
~/.claude/agents/ (user)
Plugin agents (lowest)
When names collide, higher priority wins.
Required Frontmatter Fields
name
Lowercase letters, numbers, hyphens only
Max 64 characters, no < or > characters
Cannot contain "anthropic" or "claude"
Must match filename (minus .md)
description
Claude sees ONLY name and description when deciding to delegate. The body loads AFTER delegation — making the
description the highest-leverage field.
Formula:[What it does in 1 sentence]. [When to use it — specific trigger context].
Rules:
Lead with what the agent does, not a slogan or tagline
State when to use it — specific contexts and trigger conditions
Include "use proactively" to encourage automatic delegation
Keep execution instructions out of the description — those belong in the body
Max 1024 characters, no < or > characters
Good:
description:"Expert code review specialist. Use proactively after writing or modifying code."description:"PostgreSQL expert for query optimization and schema design. Use when working
with .sql files or database performance issues."
Bad:
description:"Helps with code"# Too vaguedescription:"Review code. Steps: 1. Read 2..."# Execution details
Key Optional Fields
tools — allowlist of tools the subagent can use. Inherits ALL parent tools if omitted. Principle: grant minimum
necessary permissions.
model — haiku (quick searches, cheap), sonnet (everyday coding), opus (complex reasoning), inherit
(default)
permissionMode — default, acceptEdits, auto, dontAsk, bypassPermissions, plan. Subagents inherit
parent permissions and can restrict further, but cannot escalate.
skills — skills to inject into subagent context. Subagents don't inherit skills from parent.
hooks — lifecycle hooks scoped to this subagent (PreToolUse, PostToolUse, Stop → SubagentStop)
memory — user, project, or local for persistent cross-session storage
isolation — worktree runs the subagent in a temporary git worktree (safe experimentation)
background — true to always run as a background task (main agent continues working)
Full field reference with constraints: see [${CLAUDE_SKILL_DIR}/references/spec.md].
Writing the System Prompt
Everything after the frontmatter becomes the subagent's system prompt. Subagents receive ONLY this prompt plus basic
environment details — not the full Claude Code system prompt.
Structure Template
You are a [role] specializing in [domain].
## When Invoked1. [First action]
2. [Second action]
3. [Continue until complete]
## Guidelines- [Guideline 1]
- [Guideline 2]
## Constraints- [Boundary 1 — what NOT to do]
## Output Format
[Specify exact structure with example]
System Prompt Rules
Start with role definition. "You are a [role] specializing in [domain]."
Use numbered steps for workflow. Explicit ordering prevents skipped steps.
Specify output format explicitly. Include a concrete example of the expected structure.
Add constraints to prevent scope creep. "DO NOT modify files", "ONLY report findings."
Add completion criteria. "Your task is COMPLETE when: [criteria]." Prevents both early termination and over-work.
Keep single responsibility. If listing multiple unrelated capabilities, split into separate agents.
Add efficiency instructions. "Use Grep to locate relevant code BEFORE reading entire files. Return concise
summaries, not raw data."
Built-in Subagents
Explore — fast, read-only codebase search. Model: Haiku. Tools: read-only. Invoked with thoroughness level:
quick, medium, or very thorough.
Plan — read-only research for plan mode. Model: inherits. Cannot spawn subagents.
general-purpose — complex multi-step tasks. Model: inherits. Tools: all. Default when no type specified.
Bash — command execution in separate context. Model: inherits.
claude-code-guide — questions about Claude Code features. Model: Haiku.
Agent Teams
Agent Teams scale subagents into coordinated crews with a shared task list and peer messaging:
Team lead creates the team with TeamCreate, creates tasks with TaskCreate, spawns teammates with team_name
Teammates claim tasks, work independently, communicate via SendMessage, mark tasks completed
Shared task list — all agents can read, update, and create tasks. Dependencies via blockedBy.
Idle notification — teammates automatically notify the lead when idle. This is normal, not an error.
When to use teams vs standalone subagents:
Standalone: tasks are fully independent, no coordination needed
Teams: tasks share findings, have dependencies, or need lead/worker structure
Standalone subagents pollute the caller's context (TaskOutput injects full output). Teammates communicate via short
SendMessage summaries — much more context-efficient.
Architecture patterns and team examples: see [${CLAUDE_SKILL_DIR}/references/patterns.md].
Evaluation Criteria
When evaluating a subagent, assess five dimensions:
