--- name: agent-skill-templates description: Comprehensive templates, patterns, and best practices for creating Claude Code subagents and skills. Use when building new agents/skills or need reference examples for proper structure and formatting. --- # Agent & Skill Templates ## Purpose This skill provides comprehensive templates, patterns, and examples for creating well-structured Claude Code subagents and skills. Use this as a reference when building new agents or skills, or when improving existing ones. ## Context Quality agents and skills follow consistent patterns and best practices. This skill codifies those patterns into reusable templates that ensure: - Proper YAML frontmatter structure - Clear, comprehensive documentation - Appropriate tool selection - Effective system prompts - Well-organized supporting files ## Quick Reference ### When to Use What **Use a Subagent when:** - Task requires independent AI reasoning - Need context isolation from main conversation - Specialized tool set required - Recurring complex tasks - Want proactive automation **Use a Skill when:** - Documenting processes/conventions - Teaching domain-specific knowledge - Providing templates and references - Sharing team standards - Defining workflows ## Subagent Templates ### Template 1: Read-Only Analyzer Agent **Use for:** Code reviewers, security scanners, analyzers ```yaml --- name: [agent-name] description: [Clear, keyword-rich description explaining when to use this agent. Include action verbs users might say like 'review', 'analyze', 'check'. Specify if proactive.] tools: Read, Grep, Glob, Bash proactive: [true/false] --- # [Agent Title] You are a [role/specialty] specializing in [domain/expertise]. ## Your Responsibilities 1. **[Primary Responsibility]** - [Specific task 1] - [Specific task 2] - [Specific task 3] 2. **[Secondary Responsibility]** - [Specific task 1] - [Specific task 2] 3. **[Tertiary Responsibility]** - [Specific task 1] - [Specific task 2] ## Analysis Process 1. **[Step 1 Name]** - Use [tool] to [action] - Identify [what to look for] - Document [what to capture] 2. **[Step 2 Name]** - Analyze [what] - Consider [factors] - Evaluate [criteria] 3. **[Step 3 Name]** - Generate [output] - Structure findings by [organization] - Prioritize by [criteria] ## Output Format You MUST return results in this exact format: ```markdown # [Analysis Type] Summary ## Overview [Brief summary of what was analyzed] ## Critical Issues ### 1. [Issue Title] **Location:** [file:line or section] **Problem:** [Description] **Impact:** [Why this matters] **Recommendation:** [Specific fix] ## Major Issues [Same format] ## Minor Issues [Same format] ## Suggestions [Same format] ## Positive Observations - ✅ [Good practice identified] - ✅ [Good practice identified] ## Summary [Overall assessment and next steps] ``` ## Guidelines 1. **[Guideline 1 Title]** - [Specific guidance] - [Example or clarification] 2. **[Guideline 2 Title]** - [Specific guidance] - [Example or clarification] 3. **[Guideline 3 Title]** - [Specific guidance] - [Example or clarification] ## What to Look For ### [Category 1] - [Specific item to check] - [Specific item to check] - [Specific item to check] ### [Category 2] - [Specific item to check] - [Specific item to check] ## Constraints - Do NOT [action you should not take] - Do NOT [another prohibited action] - ONLY use [allowed tools/methods] - Focus on [what to focus on] - Limit [what to limit] ## Examples ### Example 1: [Scenario] **Input:** [What user provides] **Expected Analysis:** [What you should analyze] **Output:** [What format to return] ### Example 2: [Another Scenario] [Same pattern] ``` ### Template 2: Generator/Writer Agent **Use for:** Test generators, documentation writers, code generators ```yaml --- name: [agent-name] description: [Clear description. Include keywords like 'generate', 'create', 'write'. Explain what it generates and following what standards.] tools: Read, Write, Edit, Bash proactive: [false typically - generation usually needs user approval] --- # [Agent Title] You are a [role] specializing in generating [what you generate]. ## Your Responsibilities 1. **[Generation Responsibility]** - Analyze [source material] - Generate [output type] - Follow [standards/conventions] - Ensure [quality criteria] 2. **[Quality Assurance]** - Verify [what to verify] - Validate [what to validate] - Check [what to check] 3. **[Documentation]** - Document [what to document] - Include [what to include] ## Generation Process 1. **[Step 1: Analysis]** - Read [source files] - Understand [what to understand] - Identify [what to identify] 2. **[Step 2: Planning]** - Determine [what to determine] - Organize [how to organize] - Structure [how to structure] 3. **[Step 3: Generation]** - Create [what to create] - Follow [conventions/skill] - Apply [patterns/templates] 4. **[Step 4: Validation]** - Verify [what to verify] - Test [what to test] - Confirm [what to confirm] ## Standards to Follow Consult these skills for conventions: - `[relevant-skill-name]`: For [what standards] - `[another-skill-name]`: For [what standards] ## Output Format Generated files should follow this structure: ```[language] // [Header/documentation] [Standard file structure] ``` ## Guidelines 1. **[Guideline about quality]** - [Specific requirement] - [Example] 2. **[Guideline about conventions]** - [Specific requirement] - [Example] 3. **[Guideline about completeness]** - [Specific requirement] - [Example] ## Templates Use these templates when generating: ### [Template 1 Name] ```[language] [Template content] ``` ### [Template 2 Name] ```[language] [Template content] ``` ## Constraints - Do NOT generate [what not to generate] - ALWAYS include [what must be included] - MUST follow [what must be followed] - Verify [what to verify] before writing ## Examples ### Example: [Use Case] **Input:** [What user provides] **Analysis:** [What you determine] **Generated Output:** ```[language] [Example of generated content] ``` ## Validation Checklist After generation, verify: - [ ] [Verification item 1] - [ ] [Verification item 2] - [ ] [Verification item 3] - [ ] [Verification item 4] ``` ### Template 3: Specialist Agent (Domain Expert) **Use for:** Security specialists, performance optimizers, architecture advisors ```yaml --- name: [agent-name] description: [Clear description of domain expertise. Include technical terms and concepts. Explain when to consult this specialist.] tools: Read, Grep, Glob, [Write/Edit if making changes] proactive: [usually false - consultation is user-initiated] --- # [Agent Title] You are a [domain] specialist with deep expertise in [specific areas]. ## Your Expertise 1. **[Expertise Area 1]** - [Specific knowledge/capability] - [Specific knowledge/capability] - [Specific knowledge/capability] 2. **[Expertise Area 2]** - [Specific knowledge/capability] - [Specific knowledge/capability] 3. **[Expertise Area 3]** - [Specific knowledge/capability] - [Specific knowledge/capability] ## When to Consult You Users should invoke you for: - [Scenario 1] - [Scenario 2] - [Scenario 3] - [Scenario 4] ## Consultation Process 1. **[Understand the Problem]** - Clarify [what needs clarification] - Gather [what information needed] - Analyze [what to analyze] 2. **[Apply Expertise]** - Evaluate [using what criteria] - Consider [what factors] - Assess [what aspects] 3. **[Provide Recommendations]** - Suggest [type of recommendations] - Explain [what to explain] - Justify [reasoning] - Offer alternatives ## Recommendation Format ```markdown # [Domain] Consultation ## Problem Analysis [What you understand the problem to be] ## Key Considerations 1. [Consideration 1] 2. [Consideration 2] 3. [Consideration 3] ## Recommendations ### Option 1: [Approach Name] (Recommended) **Pros:** - [Pro 1] - [Pro 2] **Cons:** - [Con 1] - [Con 2] **Implementation:** [How to implement] ### Option 2: [Alternative Approach] **Pros:** - [Pro 1] **Cons:** - [Con 1] **When to use:** [Specific scenarios] ### Option 3: [Another Alternative] [Same format] ## Recommended Decision [Your recommendation with justification] ## Next Steps 1. [Action step 1] 2. [Action step 2] 3. [Action step 3] ``` ## Domain Knowledge ### [Concept/Pattern 1] [Explanation of key concept in your domain] Best practices: - [Best practice 1] - [Best practice 2] Common pitfalls: - [Pitfall 1] - [Pitfall 2] ### [Concept/Pattern 2] [Similar format] ## Guidelines 1. **[Always do this]** - [Specific guidance] 2. **[Never do this]** - [Specific guidance] 3. **[Consider this]** - [Specific guidance] ## Constraints - Recommendations must [requirement] - Analysis should [requirement] - Do NOT [prohibition] ## Reference Materials Key principles from [framework/standard]: - [Principle 1] - [Principle 2] - [Principle 3] ``` ### Template 4: Process Guide Agent **Use for:** Deployment guides, workflow managers, procedure executors ```yaml --- name: [agent-name] description: [Clear description of process being guided. Include process steps and when to use. Often references a skill for the documented procedure.] tools: Read, Bash, [Write if creating artifacts] proactive: [false - processes need user initiation] --- # [Agent Title] You are a [process] guide who helps users through [specific procedure]. ## Your Responsibilities 1. **[Lead Through Process]** - Guide user step-by-step - Verify prerequisites - Check completion of each step - Handle errors and issues 2. **[Ensure Safety]** - Validate before proceeding - Prevent common mistakes - Provide rollback if needed 3. **[Documentation]** - Record what was done - Document any issues - Note deviations from standard ## Process Overview The [process name] consists of these phases: 1. [Phase 1]: [Brief description] 2. [Phase 2]: [Brief description] 3. [Phase 3]: [Brief description] 4. [Phase 4]: [Brief description] ## Process Execution ### Phase 1: [Phase Name] **Checklist:** - [ ] [Prerequisite 1] - [ ] [Prerequisite 2] - [ ] [Prerequisite 3] **Steps:** 1. [Step 1] ```bash [Command if applicable] ``` **Expected result:** [What should happen] 2. [Step 2] [Instructions] **Verification:** [How to verify] **Proceed only after all steps complete successfully.** ### Phase 2: [Phase Name] [Similar format] ### Phase 3: [Phase Name] [Similar format] ### Phase 4: [Phase Name] [Similar format] ## Error Handling ### If [Error Scenario 1] occurs: 1. [Recovery step 1] 2. [Recovery step 2] 3. [When to retry vs rollback] ### If [Error Scenario 2] occurs: [Similar format] ## Rollback Procedure If process must be aborted: 1. [Rollback step 1] 2. [Rollback step 2] 3. [Rollback step 3] ## Verification After process completion, verify: - [ ] [Verification 1] - [ ] [Verification 2] - [ ] [Verification 3] Commands to verify: ```bash [Verification commands] ``` ## Communication Style - Ask user to confirm before each phase - Explain what will happen before doing it - Report results after each step - Pause and ask if errors occur - Summarize at end ## Guidelines 1. **Never skip verification steps** 2. **Always wait for user confirmation before proceeding** 3. **Document any deviations from standard procedure** 4. **Provide clear rollback instructions if issues occur** ## Constraints - Do NOT proceed if prerequisites not met - Do NOT skip safety checks - MUST get user confirmation for destructive operations - MUST provide rollback option ## Example Session ``` Agent: "Starting [process]. First, I'll verify prerequisites..." [Checks prerequisites] Agent: "All prerequisites met. Ready to proceed with Phase 1: [name]. This will [what it does]. Proceed? (yes/no)" User: "yes" Agent: "Executing Phase 1..." [Performs steps] [Reports results] Agent: "Phase 1 complete. Results: [summary]. Proceed to Phase 2? (yes/no)" [Continues through phases] ``` ``` ## Skill Templates ### Template 1: Conventions/Standards Skill **Use for:** Coding standards, testing conventions, style guides ```yaml --- name: [skill-name] description: [What conventions/standards this documents. Include framework names, technologies, and when to apply these standards.] allowed-tools: Read, Write, Edit, Bash --- # [Skill Title] ## Purpose This skill defines [what standards] for [what area of the project]. Use when [situations where this applies]. ## Philosophy Our approach to [topic] is based on: 1. [Principle 1]: [Explanation] 2. [Principle 2]: [Explanation] 3. [Principle 3]: [Explanation] ## Project Structure ``` [directory-structure]/ ├── [subdirectory]/ │ ├── [pattern]/ │ └── [pattern]/ └── [subdirectory]/ ``` **Organization:** - [Directory]: [What goes here] - [Directory]: [What goes here] - [Directory]: [What goes here] ## Naming Conventions ### [Type 1] Names - **Format:** [pattern] - **Example:** [example] - **Rules:** - [Rule 1] - [Rule 2] ### [Type 2] Names [Similar format] ## Code Standards ### [Category 1] ❌ **Bad:** ```[language] [Bad example with explanation] ``` **Why bad:** [Explanation] ✅ **Good:** ```[language] [Good example with explanation] ``` **Why good:** [Explanation] ### [Category 2] [Similar format] ## Patterns to Use ### Pattern 1: [Pattern Name] **When to use:** [Scenario] **Implementation:** ```[language] [Pattern implementation] ``` **Example:** ```[language] [Complete example] ``` ### Pattern 2: [Pattern Name] [Similar format] ## Patterns to Avoid ### Anti-Pattern 1: [Name] **Problem:** [What's wrong] ❌ **Don't do this:** ```[language] [Anti-pattern example] ``` ✅ **Do this instead:** ```[language] [Correct pattern] ``` **Reason:** [Why the correct way is better] ## Best Practices 1. **[Practice 1]** - [Specific guideline] - [Why it matters] - Example: ```[language] [Example] ``` 2. **[Practice 2]** [Similar format] 3. **[Practice 3]** [Similar format] ## Common Pitfalls ### Pitfall 1: [Name] **What happens:** [Description of problem] **How to avoid:** - [Solution 1] - [Solution 2] **Example:** ```[language] // Pitfall [Bad code] // Solution [Good code] ``` ### Pitfall 2: [Name] [Similar format] ## Checklist Use this to verify compliance: - [ ] [Check 1] - [ ] [Check 2] - [ ] [Check 3] - [ ] [Check 4] ## Tools and Configuration ### [Tool 1] **Configuration:** ```[config-format] [Configuration file content] ``` **Usage:** ```bash [Command to run tool] ``` ### [Tool 2] [Similar format] ## Related Skills - **[related-skill-1]**: [When to use instead/together] - **[related-skill-2]**: [Relationship] ## References - [External documentation link] - [Internal wiki/docs] - [Standards documentation] ``` ### Template 2: Process Documentation Skill **Use for:** Deployment processes, CI/CD workflows, incident response ```yaml --- name: [skill-name] description: [What process this documents. Include keywords for when this process applies and what triggers it.] allowed-tools: Read, Write, Bash --- # [Skill Title] ## Purpose This skill documents the [process name] procedure for [context]. Use when [triggering scenarios]. ## Prerequisites Before starting: - [ ] [Requirement 1] - [ ] [Requirement 2] - [ ] [Requirement 3] **How to verify:** ```bash [Commands to check prerequisites] ``` ## Process Overview ``` [Phase 1] → [Phase 2] → [Phase 3] → [Phase 4] ↓ ↓ ↓ ↓ [Tasks] [Tasks] [Tasks] [Tasks] ``` **Timeline:** [Expected duration] **Participants:** [Who's involved] ## Phase 1: [Phase Name] ### Objective [What this phase accomplishes] ### Steps #### Step 1: [Step Name] **Action:** [What to do] **Commands:** ```bash [Commands to execute] ``` **Expected Output:** ``` [What you should see] ``` **Verification:** ```bash [How to verify success] ``` #### Step 2: [Step Name] [Similar format] ### Completion Criteria - [ ] [Criterion 1] - [ ] [Criterion 2] ## Phase 2: [Phase Name] [Similar format to Phase 1] ## Phase 3: [Phase Name] [Similar format] ## Phase 4: [Phase Name] [Similar format] ## Error Handling ### Error: [Error Type 1] **Symptoms:** - [Symptom 1] - [Symptom 2] **Diagnosis:** ```bash [Commands to diagnose] ``` **Resolution:** 1. [Resolution step 1] 2. [Resolution step 2] **Prevention:** [How to prevent this error] ### Error: [Error Type 2] [Similar format] ## Rollback Procedure If the process must be aborted: ### Step 1: [Rollback Step] ```bash [Rollback commands] ``` ### Step 2: [Rollback Step] [Continue] ### Verification After Rollback ```bash [Verify system state] ``` ## Best Practices 1. **[Practice 1]** - [Why this matters] - [How to apply] 2. **[Practice 2]** [Similar format] ## Common Mistakes ### Mistake 1: [Description] **Problem:** [What goes wrong] **Solution:** [How to avoid] ### Mistake 2: [Description] [Similar format] ## Checklists ### Pre-Process Checklist - [ ] [Item 1] - [ ] [Item 2] - [ ] [Item 3] ### During Process Checklist - [ ] [Item 1] - [ ] [Item 2] ### Post-Process Checklist - [ ] [Item 1] - [ ] [Item 2] ## Supporting Scripts ### Script: [script-name.sh] **Location:** `scripts/[script-name].sh` **Purpose:** [What it does] **Usage:** ```bash ./scripts/[script-name].sh [arguments] ``` **Parameters:** - `[param1]`: [Description] - `[param2]`: [Description] ## Templates ### Template: [Template Name] **Location:** `templates/[template-file]` **Usage:** 1. Copy template 2. Replace placeholders: - `[PLACEHOLDER1]`: [What to put] - `[PLACEHOLDER2]`: [What to put] 3. Save to [location] ## Related Skills - **[related-skill]**: [How they relate] ## References - [Documentation links] - [Runbook links] - [Team wiki] ``` ### Template 3: Technical Domain Knowledge Skill **Use for:** API design patterns, security practices, architecture patterns ```yaml --- name: [skill-name] description: [What domain knowledge this provides. Include technical terms, concepts, and when this knowledge applies.] --- # [Skill Title] ## Purpose This skill provides guidance on [domain topic] for [context]. Use when [scenarios]. ## Core Concepts ### Concept 1: [Name] **Definition:** [Clear definition] **When to use:** [Scenarios] **How it works:** [Explanation with diagrams if helpful] **Example:** ```[language/format] [Concrete example] ``` ### Concept 2: [Name] [Similar format] ### Concept 3: [Name] [Similar format] ## Design Patterns ### Pattern 1: [Pattern Name] **Intent:** [What problem this solves] **When to use:** - [Scenario 1] - [Scenario 2] - [Scenario 3] **Structure:** ``` [ASCII diagram or description of pattern structure] ``` **Implementation:** ```[language] [Code example showing pattern] ``` **Pros:** - [Advantage 1] - [Advantage 2] **Cons:** - [Limitation 1] - [Limitation 2] **Example:** ```[language] [Complete working example] ``` ### Pattern 2: [Pattern Name] [Similar format] ## Decision Framework When deciding [what to decide]: ``` Question 1: [Decision question]? ├─ Yes → [Recommendation A] │ └─ Use: [Pattern/approach] └─ No → Question 2: [Next decision]? ├─ Yes → [Recommendation B] └─ No → [Recommendation C] ``` ## Best Practices ### Practice 1: [Name] **Principle:** [Core principle] **Why it matters:** [Explanation] **How to apply:** 1. [Step 1] 2. [Step 2] ❌ **Wrong:** ```[language] [Bad example] ``` ✅ **Right:** ```[language] [Good example] ``` ### Practice 2: [Name] [Similar format] ## Common Mistakes ### Mistake 1: [Anti-Pattern Name] **Problem:** [What people do wrong] **Why it's wrong:** [Consequences] **Impact:** - [Negative impact 1] - [Negative impact 2] **How to fix:** ```[language] // Before (wrong) [Wrong code] // After (correct) [Correct code] ``` ### Mistake 2: [Anti-Pattern Name] [Similar format] ## Examples ### Example 1: [Real-World Scenario] **Context:** [Situation] **Requirements:** - [Requirement 1] - [Requirement 2] **Solution:** ```[language] [Complete implementation] ``` **Explanation:** [Why this solution works] ### Example 2: [Another Scenario] [Similar format] ## Advanced Topics ### Topic 1: [Advanced Concept] [Explanation for experienced users] ### Topic 2: [Advanced Concept] [Similar format] ## Trade-Offs ### Trade-Off 1: [A vs B] **Option A: [Approach A]** - Pros: [Pros] - Cons: [Cons] - When to choose: [Scenarios] **Option B: [Approach B]** - Pros: [Pros] - Cons: [Cons] - When to choose: [Scenarios] ## Related Skills - **[related-skill-1]**: [Relationship] - **[related-skill-2]**: [Relationship] ## Further Reading - [External resource 1] - [External resource 2] - [Internal documentation] ``` ## Supporting File Templates ### Template: Unit Test Template **Location:** `templates/unit-test.template` ```javascript // tests/unit/[module-name].test.js import { describe, it, expect, beforeEach, afterEach } from 'vitest' import { [ClassOrFunction] } from '@/[path]' describe('[ClassOrFunction]', () => { let [instance] beforeEach(() => { // Setup before each test [instance] = new [ClassOrFunction]() }) afterEach(() => { // Cleanup after each test }) describe('[methodName]', () => { it('should [expected behavior] when [condition]', () => { // Arrange const [input] = { /* test data */ } // Act const result = [instance].[methodName]([input]) // Assert expect(result).toEqual(/* expected output */) }) it('should throw [ErrorType] when [invalid condition]', () => { // Arrange const [invalidInput] = { /* invalid data */ } // Act & Assert expect(() => [instance].[methodName]([invalidInput])) .toThrow([ErrorType]) }) it('should [edge case behavior]', () => { // Test edge cases }) }) }) ``` ### Template: Integration Test Template **Location:** `templates/integration-test.template` ```javascript // tests/integration/[module-name].integration.test.js import { describe, it, expect, beforeAll, afterAll } from 'vitest' import { setupTestDatabase, teardownTestDatabase } from '@/tests/helpers/db' import request from 'supertest' import app from '@/app' describe('[Feature] Integration Tests', () => { beforeAll(async () => { await setupTestDatabase() }) afterAll(async () => { await teardownTestDatabase() }) describe('[HTTP_METHOD] /[endpoint]', () => { it('should return [status] with [expected data] when [condition]', async () => { // Arrange const [requestData] = { // Request payload } // Act const response = await request(app) .[method]('/[endpoint]') .send([requestData]) // Assert expect(response.status).toBe([expectedStatus]) expect(response.body).toMatchObject({ // Expected response shape }) }) it('should return [error status] when [error condition]', async () => { // Test error scenarios }) }) }) ``` ### Template: Agent Creation Script **Location:** `templates/create-agent.sh` ```bash #!/bin/bash # Agent Creation Helper Script # Usage: ./create-agent.sh # Types: analyzer, generator, specialist, process-guide AGENT_NAME=$1 AGENT_TYPE=${2:-"analyzer"} if [ -z "$AGENT_NAME" ]; then echo "Usage: $0 [agent-type]" echo "Types: analyzer, generator, specialist, process-guide" exit 1 fi AGENT_FILE=".claude/agents/${AGENT_NAME}.md" mkdir -p .claude/agents case $AGENT_TYPE in "analyzer") TOOLS="Read, Grep, Glob, Bash" ROLE="analyzer" ;; "generator") TOOLS="Read, Write, Edit, Bash" ROLE="generator" ;; "specialist") TOOLS="Read, Grep, Glob" ROLE="specialist" ;; "process-guide") TOOLS="Read, Bash" ROLE="process guide" ;; *) echo "Unknown type: $AGENT_TYPE" exit 1 ;; esac cat > "$AGENT_FILE" < # Types: conventions, process, domain-knowledge SKILL_NAME=$1 SKILL_TYPE=${2:-"conventions"} if [ -z "$SKILL_NAME" ]; then echo "Usage: $0 [skill-type]" echo "Types: conventions, process, domain-knowledge" exit 1 fi SKILL_DIR=".claude/skills/${SKILL_NAME}" SKILL_FILE="${SKILL_DIR}/SKILL.md" mkdir -p "$SKILL_DIR" mkdir -p "${SKILL_DIR}/templates" mkdir -p "${SKILL_DIR}/examples" cat > "$SKILL_FILE" <