This skill should be used when the user asks to "create an agent", "add a subagent", "write an agent", "agent frontmatter", "agent file format", "agent tools", "agent model", "permissionMode", or needs guidance on subagent structure, system prompts, triggering conditions, or agent development best practices for Claude Code.
/plugin marketplace add astrosteveo/claude-code-plugins/plugin install astrosteveo-plugin-dev-plugins-plugin-dev@astrosteveo/claude-code-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
examples/complete-agent-examples.mdreferences/best-practices.mdreferences/subagents.mdreferences/system-prompt-design.mdscripts/validate-agent.shSubagents are specialized AI assistants that Claude Code can delegate tasks to. Each subagent has its own context window, custom system prompt, and configurable tool access. This skill covers how to create and configure subagents properly.
Key concepts:
| Type | Location | Scope | Priority |
|---|---|---|---|
| Project subagents | .claude/agents/ | Current project only | Highest |
| User subagents | ~/.claude/agents/ | All projects | Lower |
| Plugin agents | agents/ in plugin root | When plugin installed | Via plugin |
When names conflict, project-level subagents take precedence over user-level.
Each subagent is a Markdown file with YAML frontmatter:
---
name: your-agent-name
description: Description of when this subagent should be invoked
tools: Read, Grep, Glob, Bash
model: sonnet
color: blue
permissionMode: default
skills: skill1, skill2
---
Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.
Include specific instructions, best practices, and any constraints
the subagent should follow.
| Field | Required | Description |
|---|---|---|
name | Yes | Unique identifier using lowercase letters and hyphens |
description | Yes | Natural language description of when to invoke (simple string) |
tools | No | Comma-separated list of tools. If omitted, inherits all tools |
model | No | Model alias (sonnet, opus, haiku) or inherit. Default: sonnet |
color | No | Visual identifier: blue, cyan, green, yellow, magenta, red |
permissionMode | No | default, acceptEdits, bypassPermissions, plan, or ignore |
skills | No | Comma-separated list of skill names to auto-load |
Unique identifier for the subagent.
Format: Lowercase letters, numbers, and hyphens only (2-50 characters)
Examples: code-reviewer, test-runner, api-analyzer
A simple, natural language string describing when Claude should invoke this agent.
IMPORTANT: The description is a plain string. Do NOT include:
<example> or <commentary>\nGood descriptions:
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks.
Bad descriptions (DO NOT USE):
# WRONG - contains XML tags
description: Use this agent when... Examples:\n\n<example>\nuser: "review my code"\n</example>
# WRONG - contains escape sequences
description: Use this agent when the user asks to review code.\nAlso use when...
Tips for effective descriptions:
Comma-separated list of tools the agent can use.
tools: Read, Grep, Glob, Bash
Available tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, and any MCP tools
Default behavior: If omitted, the agent inherits all tools from the main thread, including MCP tools.
Best practice: Limit to only necessary tools (principle of least privilege).
Which model the subagent should use.
Options:
sonnet - Claude Sonnet (default if omitted)opus - Claude Opus (most capable)haiku - Claude Haiku (fastest, cheapest)inherit - Use same model as main conversationmodel: inherit
Environment variable: Set CLAUDE_CODE_SUBAGENT_MODEL to configure the default model for all subagents.
Visual identifier for the agent in the UI.
Options: blue, cyan, green, yellow, magenta, red
color: blue
Note: The color field is implemented in Claude Code but not documented in the official specification. It works reliably but may change in future versions.
Guidelines:
Controls how the subagent handles permission requests.
Options:
default - Normal permission behavioracceptEdits - Auto-accept file editsbypassPermissions - Skip permission promptsplan - Planning mode onlyignore - Ignore permission systemComma-separated list of skills to auto-load when the subagent starts.
skills: api-testing, code-standards
The markdown body after the frontmatter becomes the agent's system prompt. Write clear, specific instructions.
You are [role description] specializing in [domain].
When invoked:
1. [First step]
2. [Second step]
3. [Third step]
[Domain-specific guidance]:
- [Guideline 1]
- [Guideline 2]
- [Guideline 3]
For each [task type], provide:
- [Output element 1]
- [Output element 2]
- [Output element 3]
[Additional constraints or best practices]
DO:
DON'T:
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples of how to fix issues.
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states
For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations
Focus on fixing the underlying issue, not the symptoms.
---
name: test-runner
description: Test automation expert. Use proactively to run tests after code changes and fix any failures.
tools: Read, Edit, Bash, Grep, Glob
---
You are a test automation expert ensuring code quality through comprehensive testing.
When invoked:
1. Identify which tests are relevant to recent changes
2. Run the appropriate test suite
3. Analyze any failures
4. Fix failing tests while preserving original test intent
Testing process:
- Check git diff to see what changed
- Run targeted tests first, then full suite if needed
- For failures, distinguish between:
- Test bugs (fix the test)
- Code bugs (fix the code)
- Intentional changes (update test expectations)
For each test failure, provide:
- What failed and why
- Root cause analysis
- The fix applied
- Verification that fix works
You can define subagents dynamically using the --agents CLI flag with JSON:
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'
Key differences from file-based agents:
prompt field instead of markdown body for system promptUse cases:
Claude Code includes three built-in agents:
Plugin agents are stored in the agents/ directory at the plugin root:
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── agents/
│ ├── code-reviewer.md
│ ├── test-runner.md
│ └── debugger.md
└── ...
All .md files in agents/ are auto-discovered when the plugin is loaded.
The /agents command provides an interactive interface:
/agentsagents/my-agent.mdAn agent file is valid when:
--- markers\n escapes)inherit, sonnet, opus, or haikudefault, acceptEdits, bypassPermissions, plan, or ignoreUse scripts/validate-agent.sh to check agent files.
Automatic: Claude delegates based on task matching the description:
> Review my recent code changes
[Claude automatically invokes code-reviewer agent]
Explicit: Mention the agent by name:
> Use the test-runner agent to check if my changes broke anything
Encouraging proactive use: Include phrases in description like:
Agents can be resumed to continue previous conversations:
agentIdagent-{agentId}.jsonlresume parameter with the agentId to continueUse cases:
Explicit resume example:
> Resume agent abc123 and now analyze the authorization logic as well
Programmatic usage (Task tool):
{
"description": "Continue analysis",
"prompt": "Now examine the error handling patterns",
"subagent_type": "code-analyzer",
"resume": "abc123"
}
Claude Code displays the agent ID when a subagent completes its work.
references/best-practices.md - Consolidated best practices for agent developmentreferences/subagents.md - Official Claude Code subagents documentationreferences/system-prompt-design.md - Detailed system prompt patternsexamples/complete-agent-examples.md - More working examplesscripts/validate-agent.sh - Validation utilityThis skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.