Comprehensive guide for creating Claude Code agents with proper structure, triggering conditions, system prompts, and validation - combines official Anthropic best practices with proven patterns

Create Agent Command Create autonomous Claude Code agents that handle complex, multi step tasks independently. This command provides comprehensive guidance based on official Anthropic documentation and proven patterns. User Input What Are Agents? Agents are autonomous subprocesses spawned via the Task tool that: Handle complex, multi step tasks independently Have their own isolated context window Return results to the parent conversation Can be specialized for specific domains Concept Agent Command Trigger Claude decides based on description User invokes with /name Purpose Autonomous work User initiated actions Context Isolated subprocess Shared conversation File format agents/ .md commands/ .md Agent File Structure Agents use a unique format combining YAML frontmatter with a markdown system prompt : Frontmatter Fields Reference Required Fields name (Required) Format : Lowercase with hyphens only Length : 3 50 characters Rules : Must start and end with alphanumeric character Only lowercase letters, numbers, and hyphens No underscores, spaces, or special characters Valid Invalid Reason code reviewer helper Too generic test generator agent Starts/ends with hyphen api docs writer my agent Underscores not allowed security analyzer ag Too short (<3 chars) pr quality reviewer MyAgent Uppercase not allowed description (Required, Critical) The most important field Defines when Claude triggers the agent. Requirements : Length: 10 5,000 characters (ideal: 200 1,000 with 2 4 examples) MUST start with : "Use this agent when..." MUST include : <example blocks showing usage patterns Each example needs: context, user request, assistant response, commentary Example Block Format : Best Practices for Descriptions : Include 2 4 concrete examples Show both proactive and reactive triggering scenarios Cover different phrasings of the same intent Explain reasoning in commentary Be specific about when NOT to use the agent model (Required) Values : inherit , sonnet , opus , haiku Default : inherit (recommended) Value Use Case Cost inherit Use parent conversation model Default haiku Fast, simple tasks Lowest sonnet Balanced performance Medium opus Maximum capability, complex reasoning Highest Recommendation : Use inherit unless you have a specific reason to override. color (Required) Purpose : Visual indicator in UI to distinguish agents Values : blue , cyan , green , yellow , magenta , red Best Practice : Use different colors for different agents in the same plugin to distinguish them visually. Optional Fields tools (Optional) Purpose : Restrict available tools (principle of least privilege) Format : Array of tool names Default : All tools available Security Principle : Only grant tools the agent actually needs. Triggering Patterns Pattern 1: Explicit Request User directly asks for the agent's function. Pattern 2: Implicit Need Agent needed based on context, not explicit request. Pattern 3: Proactive Trigger Agent triggers after completing relevant work without explicit request. Pattern 4: Tool Usage Pattern Agent triggers based on prior tool usage. System Prompt Design The system prompt (markdown body after frontmatter) defines agent behavior. Use this proven template: System Prompt Principles Principle Good Bad Be specific "Check for SQL injection in query strings" "Look for security issues" Include examples "Format: Critical Issues\n Issue 1 " "Use proper formatting" Define boundaries "Do NOT modify files, only analyze" No boundaries stated Provide fallbacks "If unsure, ask for clarification" Assume and proceed Quality mechanisms "Verify each finding with evidence" No verification Validation Requirements System prompts must be: Length : 20 10,000 characters (ideal: 500 3,000) Well structured : Clear sections with responsibilities, process, output format Specific : Actionable instructions, not vague guidance Complete : Handles edge cases and quality standards AI Assisted Agent Generation Use this prompt to generate agent configurations automatically: Elite Agent Architect Process When creating agents, follow this 6 step process: 1. Extract Core Intent : Identify fundamental purpose, key responsibilities, success criteria 2. Design Expert Persona : Create compelling expert identity with domain knowledge 3. Architect Comprehensive Instructions : Behavioral boundaries, methodologies, edge cases, output formats 4. Optimize for Performance : Decision frameworks, quality control, workflow patterns, fallback strategies 5. Create Identifier : Concise, descriptive, 2 4 words with hyphens 6. Generate Examples : Triggering scenarios with context, user/assistant dialogue, commentary Default Agent Standards Frontmatter Rules description : Keep to ONE sentence descriptions load into parent context, every token counts Do NOT add verbose <example blocks in description they waste context tokens Required Agent Sections (in order) 1. Title <Role Title with strong identity statement 2. Identity Quality expectations and motivation (consequences for poor work) 3. Goal Clear single paragraph objective 4. Input What files/data the agent receives 5. CRITICAL: Load Context Explicit requirement to read ALL relevant files BEFORE analysis 6. Process/Stages Step by step workflow with proper ordering Process Stage Ordering (critical for multi stage agents) Self critique comes as the last step, always Always produce everything first, then evaluate and select Decision Tables Put reasoning column BEFORE decision column: This forces the agent to explain WHY before deciding, improving decision quality. Validation Rules Structural Validation Component Rule Valid Invalid Name 3 50 chars, lowercase, hyphens code reviewer Code Reviewer Description 10 5000 chars, starts "Use this agent when" Use this agent when reviewing code... Reviews code Model One of: inherit, sonnet, opus, haiku inherit gpt 4 Color One of: blue, cyan, green, yellow, magenta, red blue purple System prompt 20 10000 chars 500+ char prompt Empty body Examples At least one <example block Has examples No examples Validation Script Quality Checklist Before deployment: [ ] Name follows conventions (lowercase, hyphens, 3 50 chars) [ ] Description starts with "Use this agent when..." [ ] Description includes 2 4 <example blocks [ ] Each example has context, user, assistant, commentary [ ] Model is appropriate for task complexity [ ] Color is unique among related agents [ ] Tools restricted to what's needed (least privilege) [ ] System prompt has clear structure [ ] Responsibilities are specific and actionable [ ] Process steps are concrete [ ] Output format is defined [ ] Edge cases are addressed Production Examples Code Quality Reviewer Agent Test Generator Agent Agent Creation Process Step 1: Gather Requirements Ask user (if not provided): 1. Agent name : What should the agent be called? (kebab case) 2. Purpose : What problem does this agent solve? 3. Triggers : When should Claude use this agent? 4. Responsibilities : What are the core tasks? 5. Tools needed : Read only? Can modify files? 6. Model : Need maximum capability (opus) or balanced (sonnet/inherit)? Step 2: Create Agent File Step 3: Write Frontmatter Generate frontmatter with: Unique, descriptive name Description with triggering conditions and examples Appropriate model setting Distinct color Minimal required tools Step 4: Write System Prompt Create system prompt following the template: 1. Role statement with specialization 2. Core responsibilities (numbered list) 3. Analysis/work process (step by step) 4. Quality standards (measurable criteria) 5. Output format (specific structure) 6. Edge cases (how to handle special situations) Step 5: Validate Run validation: Check: [ ] Frontmatter parses correctly [ ] All required fields present [ ] Examples are complete [ ] System prompt is comprehensive Step 6: Test Triggering Test with various scenarios: 1. Explicit requests matching examples 2. Implicit needs where agent should activate 3. Scenarios where agent should NOT activate 4. Edge cases and variations Best Practices Summary DO Include 2 4 concrete examples in agent descriptions Write specific, unambiguous triggering conditions Use "inherit" model setting unless specific need Apply principle of least privilege for tools Write clear, structured system prompts with explicit steps Test agent triggering thoroughly before deployment Use different colors for different agents Include commentary explaining trigger logic DON'T Generic descriptions without examples Omit triggering conditions Use same color for multiple agents in same plugin Grant unnecessary tool access Write vague system prompts Skip testing phases Use underscores or uppercase in names Forget to handle edge cases Integration with Workflows Agents integrate with plugin workflows: 1. Phase 5: Component Implementation uses agent creator to generate agents 2. Validation phase uses validate agent.sh script 3. Testing phase verifies triggering across scenarios For comprehensive plugin development, use: /plugin dev:create plugin for full plugin workflow This command for individual agent creation/refinement Create the Agent Based on user input, create: 1. Directory structure : ${CLAUDE PLUGIN ROOT}/agents/ 2. Agent file : Complete markdown with frontmatter + system prompt 3. Validation : Run validation script 4. Testing suggestions : Scenarios to verify triggering After creation, suggest testing with /customaize agent:test prompt command to verify agent behavior under various scenarios.

create-agent