/create-agent

Purpose

Create a new custom subagent (skill) for specialized tasks with proper configuration and system prompts.

Contract

Inputs:

• $1 — AGENT_NAME (lowercase, kebab-case, e.g., "code-reviewer")
• $2 — DESCRIPTION (when this agent should be invoked, e.g., "Expert code reviewer. Use proactively after code changes.")
• --user — Create user-level agent in ~/.claude/agents/ (default: project-level in .claude/agents/)
• --tools — Comma-separated list of tools (e.g., "Read,Grep,Glob,Bash")
• --model — Model to use: "sonnet", "opus", "haiku", or "inherit" (default: sonnet)

Outputs:

• STATUS=<CREATED|EXISTS|FAIL> PATH=<path> AGENT=<name>

Instructions

1. Validate inputs:

   • Agent name must be lowercase, kebab-case only
   • Description must be non-empty and descriptive
   • If --tools specified, validate tool names against available tools
   • If --model specified, validate it's one of: sonnet, opus, haiku, inherit

2. Determine file location:

   • Default: .claude/agents/{AGENT_NAME}.md (project-level)
   • With --user: ~/.claude/agents/{AGENT_NAME}.md (user-level)
   • Create directory if it doesn't exist

3. Check for existing agent:

   • If file exists, output STATUS=EXISTS and exit
   • Recommend using /agents command to edit existing agents

4. Generate agent file content:

   ---
   name: {AGENT_NAME}
   description: {DESCRIPTION}
   tools: {TOOLS}  # Optional - only include if specified
   model: {MODEL}  # Optional - only include if specified
   ---
   
   You are a specialized agent for {purpose based on description}.
   
   When invoked:
   1. Understand the specific task or problem
   2. Analyze the relevant context
   3. Execute your specialized function
   4. Provide clear, actionable results
   
   Key responsibilities:
   - {Responsibility 1 based on description}
   - {Responsibility 2 based on description}
   - {Responsibility 3 based on description}
   
   Best practices:
   - Be focused and efficient
   - Provide specific, actionable feedback
   - Document your reasoning
   - Follow established patterns and conventions
   
   For each task:
   - Explain your approach
   - Show your work
   - Highlight key findings or changes
   - Suggest next steps if applicable
   

5. Write the file:

   • Create the agent file with proper frontmatter
   • Ensure proper formatting and indentation
   • Set appropriate file permissions

6. Output result:

   • Print: STATUS=CREATED PATH={path} AGENT={name}
   • Provide usage example: Use the {name} agent to...

Examples

Basic project-level agent

/create-skill code-reviewer "Expert code review specialist. Use proactively after code changes."
# Output: STATUS=CREATED PATH=.claude/agents/code-reviewer.md AGENT=code-reviewer

User-level agent with specific tools

/create-skill debugger "Debugging specialist for errors and test failures" --user --tools "Read,Edit,Bash,Grep,Glob"
# Output: STATUS=CREATED PATH=~/.claude/agents/debugger.md AGENT=debugger

Agent with specific model

/create-skill data-scientist "Data analysis expert for SQL queries and insights" --tools "Bash,Read,Write" --model "sonnet"
# Output: STATUS=CREATED PATH=.claude/agents/data-scientist.md AGENT=data-scientist

Constraints

• Idempotent: Won't overwrite existing agents
• No network access required
• Agent names must follow naming conventions
• Tools list must match available Claude Code tools
• Model must be valid alias or 'inherit'

Best Practices

• Use descriptive, action-oriented descriptions
• Include "use PROACTIVELY" in description for automatic invocation
• Start with Claude-generated agents via /agents for complex cases
• Limit tools to only what the agent needs
• Design focused agents with single, clear responsibilities
• Add to version control for team collaboration

Related Commands

• /agents - Interactive interface for managing agents (recommended for editing)
• Use created agents: "Use the {name} agent to..."
• Invoke explicitly: "Ask the {name} agent to investigate..."