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.
Manages the full lifecycle of Claude Code subagents including creation, evaluation, iteration, and troubleshooting.
npx claudepluginhub xobotyi/cc-foundryThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/creation.mdreferences/evaluation.mdreferences/iteration.mdreferences/patterns.mdreferences/spec.mdreferences/troubleshooting.mdManage the full lifecycle of Claude Code subagents: creation, evaluation, iteration, and troubleshooting.
<prerequisite> **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). </prerequisite>
| Situation | Reference | Contents |
|---|---|---|
| Full frontmatter field reference | spec.md | All fields with constraints, hooks schema, CLI-defined agents, storage locations |
| Step-by-step creation walkthrough | creation.md | Detailed process, common agent type templates, proactive delegation |
| Quality scoring and testing | evaluation.md | 5-dimension scoring rubric with weights, testing protocol (5 levels), benchmarking |
| Improving an existing subagent | iteration.md | Prompt refinement techniques, A/B testing, version control, redesign criteria |
| Diagnosing failures | troubleshooting.md | Diagnostic steps, error message catalog, debug mode |
| Architecture and examples | patterns.md | Full agent examples, pipeline/parallel/master-clone patterns, multi-agent coordination |
Read the relevant reference for extended depth. The rules below are sufficient for correct work without loading references.
Use subagents when:
Use main conversation when:
Use skills instead when:
.claude/agents/my-agent.md # Project-level
~/.claude/agents/my-agent.md # User-level
---
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]
--agents CLI flag (session only).claude/agents/ (project)~/.claude/agents/ (user)When names collide, higher priority wins.
name< or > characters.md)descriptionClaude sees ONLY name and description when deciding to delegate.
The body loads AFTER delegation. This makes the description the
highest-leverage field.
Formula:
[What it does in 1 sentence]. [When to use it — specific trigger context].
Rules:
< or > characters.Good:
description: "Expert code review specialist. Proactively reviews code for
quality, security, and maintainability. Use immediately after writing
or modifying code."
description: "PostgreSQL database expert for query optimization and schema
design. Use when working with .sql files or database performance issues."
Bad:
description: "Helps with code" # Too vague
description: "Review code. Steps: 1. Read 2..." # Execution details
description: "Code review. Keywords: review..." # Keyword stuffing
toolsAllowlist of tools the subagent can use. If omitted, inherits ALL tools from the main conversation (including MCP tools). Be intentional — don't leave it blank unless you want full access.
Principle: grant minimum necessary permissions.
| Agent Type | Recommended Tools |
|---|---|
| Read-only (reviewers, analysts) | Read, Grep, Glob |
| Research (with web) | Read, Grep, Glob, WebFetch, WebSearch |
| Code writers | Read, Write, Edit, Bash, Glob, Grep |
| Documentation | Read, Write, Edit, Glob, Grep, WebFetch |
Available built-in tools: Read, Write, Edit, Bash, Glob, Grep,
WebFetch, WebSearch, Task (main agent only), NotebookEdit.
Use disallowedTools when you want most tools but need to exclude a few.
model| Value | When to Use |
|---|---|
haiku | Quick searches, docs, simple analysis — fast and cheap |
sonnet | Everyday coding, debugging, refactoring |
opus | Architecture decisions, security audits, complex reasoning |
inherit | Match parent model (default if omitted) |
permissionMode| Mode | Behavior |
|---|---|
default | Standard permission checking |
acceptEdits | Auto-accept file edits |
dontAsk | Auto-deny prompts (allowed tools still work) |
bypassPermissions | Skip all permission checks |
plan | Plan mode (read-only exploration) |
Security rules:
plan mode for read-only agents — enforce safety at the
permission level, not just in the prompt.bypassPermissions skips ALL checks including file writes and command
execution. Only use for trusted, well-tested agents.bypassPermissions, child agents inherit it and
cannot override to a more restrictive mode.skillsSkills to inject into the subagent's context at startup. Subagents don't inherit skills from parent — list them explicitly.
skills:
- api-conventions
- error-handling-patterns
hooksLifecycle hooks scoped to this subagent. Supported events:
PreToolUse, PostToolUse, Stop (converted to SubagentStop).
Full hook schema and examples: see spec.md.
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.
You are a [role] specializing in [domain].
## When Invoked
1. [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]
Description is the trigger. Claude sees ONLY name +
description when deciding to delegate. Vague descriptions cause
wrong triggers. Specific descriptions enable correct delegation.
Single responsibility. Each subagent excels at ONE task. Don't create Swiss Army knife agents — they're hard to trigger correctly and mediocre at everything.
Minimal tool access. Grant only necessary permissions. Read-only agents don't need Edit/Write. Excess tools invite scope creep.
Clear handoffs. Design subagents to return actionable summaries, not raw data dumps. The parent agent (or user) should be able to act on the output immediately.
Context efficiency. Subagents should use Grep before Read, stop when they have enough information, and return synthesized findings. Verbose returns consume parent context.
| Agent | Model | Purpose |
|---|---|---|
| Explore | Haiku | Fast, read-only codebase exploration |
| Plan | Inherits | Research for plan mode |
| general-purpose | Inherits | Complex multi-step tasks |
| Bash | Inherits | Command execution in separate context |
| claude-code-guide | Haiku | Questions about Claude Code features |
When evaluating a subagent, assess these five dimensions:
Scoring: 4.5+ excellent, 3.5-4.4 good, 2.5-3.4 needs revision, <2.5 redesign. Full rubric with testing protocol: see evaluation.md.
Description is too narrow or name has a typo. Broaden the description,
add "use proactively", and verify the file loads with /agents.
Description is too vague or overlaps with other agents. Narrow the scope, add explicit boundaries: "Security review for auth code only. NOT for general code review."
No format specification in the prompt, or no example. Add an explicit
## Output Format section with a concrete example of the expected
structure.
Workflow isn't explicit enough. Add numbered steps with "IN ORDER", a completion checklist ("Before returning, verify:"), and explicit completion criteria.
Tools are too permissive or prompt doesn't set boundaries. Restrict
the tools list and add a ## Constraints section with explicit
prohibitions.
No efficiency guidance. Add: "Use Grep to locate relevant code BEFORE reading entire files. Stop searching once you have sufficient information. Return a concise summary (max 500 words)."
Detailed diagnostic steps, error messages, and debug mode: see troubleshooting.md.
Before deploying a subagent:
name is lowercase with hyphens, no "anthropic" or "claude"description explains what AND when (under 1024 chars)description has no execution instructionstools is minimal (only what's needed)model matches task complexityprompt-engineering — Load first for instruction design techniques
(subagent prompts are system prompts)skill-engineering — Skills and subagents complement each other;
skills run in main context, subagents run in isolationclaude-code-sdk — Consult for API/configuration detailsExpert guidance for Next.js Cache Components and Partial Prerendering (PPR). **PROACTIVE ACTIVATION**: Use this skill automatically when working in Next.js projects that have `cacheComponents: true` in their next.config.ts/next.config.js. When this config is detected, proactively apply Cache Components patterns and best practices to all React Server Component implementations. **DETECTION**: At the start of a session in a Next.js project, check for `cacheComponents: true` in next.config. If enabled, this skill's patterns should guide all component authoring, data fetching, and caching decisions. **USE CASES**: Implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, debugging cache issues, and reviewing Cache Component implementations.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.