Creates or updates Claude Code agents/subagents with proper YAML frontmatter, clear system prompts, and best practices. Use when creating new agents, authoring subagents, building custom AI assistants, or when the user mentions creating an agent, subagent development, or includes `--create-agent` or `--new-agent` flag.
/plugin marketplace add outfitter-dev/agents/plugin install agent-kit@outfitterThis skill is limited to using the following tools:
Creates and updates Claude Code agents (subagents) following official best practices and conventions.
When creating a new agent:
Clarify requirements
~/.claude/agents/) or project (.claude/agents/)?Choose agent type
Generate name
[role]-[specialty] or [specialty]code-reviewer, test-runner, debugger, data-scientistWrite agent file
Test the agent
---
name: agent-name
description: When this agent should be invoked with trigger keywords
tools: Read, Grep, Glob # Optional - omit to inherit all tools
model: sonnet # Optional - sonnet, opus, haiku, or inherit
color: blue # Optional - UI visual identifier
---
# Agent Name
Your agent's system prompt goes here.
## Role and Expertise
Define who this agent is and what it specializes in.
## When Invoked
Describe the triggering conditions and what the agent does first.
## Process/Workflow
Step-by-step approach the agent follows:
1. First step
2. Second step
3. ...
## Key Practices
Important guidelines, constraints, or best practices.
## Output Format
How the agent presents results.
name (required)
[role]-[specialty] or [specialty]code-reviewer, debugger, test-runnerdescription (required)
Example:
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools (optional)
model (optional)
sonnet, opus, haiku, or inheritinherit - Use same model as main conversationsonnet)color (optional)
blue, red, yellow, green, purple, etc.Location: ~/.claude/agents/
Scope: Available across all projects
Use for: Personal workflow agents you use everywhere
mkdir -p ~/.claude/agents
Location: .claude/agents/
Scope: Available only in current project
Use for: Project-specific agents, team-shared workflows
mkdir -p .claude/agents
Priority: Project agents override user agents if names conflict.
Use the /agents command for guided creation:
/agents
This provides:
e keyCreate agent file manually:
# User agent
cat > ~/.claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Use proactively to run tests and fix failures
tools: Read, Edit, Bash
---
You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.
EOF
Test by directly requesting the agent:
> Use the code-reviewer agent to check my recent changes
> Have the test-runner agent verify my tests still pass
> Ask the debugger agent to investigate this error
Test by using trigger keywords from the description:
> Can you review this code? # Should trigger code-reviewer
> The tests are failing # Should trigger test-runner or debugger
For agents that analyze but don't modify:
tools: Read, Grep, Glob, Bash
Use for: code analyzers, security auditors, documentation reviewers
For agents that make changes:
# Omit tools field to inherit all tools
Use for: test runners, debuggers, refactoring agents
For agents needing specific capabilities:
tools: Read, Write, Bash
Use for: data scientists (need write for output), report generators
/agents to generate, then customizeAgent not being invoked automatically:
Agent has wrong tools:
tools field in frontmattertools field to inherit all tools/agents command to view/edit tool accesstools field omittedAgent giving unexpected results:
Can't find agent file:
# List all agents
ls ~/.claude/agents/
ls .claude/agents/
# Search for agent by name
find ~/.claude/agents .claude/agents -name "*test*.md" 2>/dev/null
docs/claude/subagents.md - Official subagents documentation~/.claude/agents/ - Example agents to learn from/agents command - Interactive agent managementdocs/claude/cli-reference.md - CLI --agents flag documentationThis 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.