Agent Skill Templates

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

---
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]

[Template content]

[Template 2 Name]

[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:

[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:

[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:

[Good example with explanation]

Why good: [Explanation]

[Category 2]

[Similar format]

Patterns to Use

Pattern 1: [Pattern Name]

When to use: [Scenario]

Implementation:

[Pattern implementation]

Example:

[Complete example]

Pattern 2: [Pattern Name]

[Similar format]

Patterns to Avoid

Anti-Pattern 1: [Name]

Problem: [What's wrong]

❌ Don't do this:

[Anti-pattern example]

✅ Do this instead:

[Correct pattern]

Reason: [Why the correct way is better]

Best Practices

1. [Practice 1]

   • [Specific guideline]
   • [Why it matters]
   • Example:

     [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:

// 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:

[Configuration file content]

Usage:

[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:

[Commands to execute]

Expected Output:

[What you should see]

Verification:

[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:

[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]

[Rollback commands]

Step 2: [Rollback Step]

[Continue]

Verification After Rollback

[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:

./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:

[Code example showing pattern]

Pros:

• [Advantage 1]
• [Advantage 2]

Cons:

• [Limitation 1]
• [Limitation 2]

Example:

[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:

[Bad example]

✅ Right:

[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:

// 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:

[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

// 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

#!/bin/bash

# Agent Creation Helper Script
# Usage: ./create-agent.sh <agent-name> <agent-type>
# Types: analyzer, generator, specialist, process-guide

AGENT_NAME=$1
AGENT_TYPE=${2:-"analyzer"}

if [ -z "$AGENT_NAME" ]; then
  echo "Usage: $0 <agent-name> [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" <<EOF
---
name: $AGENT_NAME
description: [FILL IN: Clear description of when to use this agent]
tools: $TOOLS
proactive: false
---

# ${AGENT_NAME^} Agent

You are a $ROLE specializing in [FILL IN: domain].

## Your Responsibilities

1. **[FILL IN: Primary Responsibility]**
   - [Task 1]
   - [Task 2]

## Guidelines

1. [FILL IN: Guideline]

## Output Format

[FILL IN: Define output structure]

## Constraints

- Do NOT [FILL IN: constraints]
EOF

echo "Created agent: $AGENT_FILE"
echo "Please edit and fill in the [FILL IN: ...] placeholders"

Template: Skill Creation Script

Location: templates/create-skill.sh

#!/bin/bash

# Skill Creation Helper Script
# Usage: ./create-skill.sh <skill-name> <skill-type>
# Types: conventions, process, domain-knowledge

SKILL_NAME=$1
SKILL_TYPE=${2:-"conventions"}

if [ -z "$SKILL_NAME" ]; then
  echo "Usage: $0 <skill-name> [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" <<EOF
---
name: $SKILL_NAME
description: [FILL IN: Clear description with keywords]
---

# ${SKILL_NAME^} Skill

## Purpose

[FILL IN: What this skill teaches and when to use it]

## Instructions

1. **[FILL IN: Step 1]**
   - [Detail]

## Examples

### Example 1: [FILL IN: Scenario]

❌ **Bad:**
\`\`\`
[Bad example]
\`\`\`

✅ **Good:**
\`\`\`
[Good example]
\`\`\`

## Best Practices

1. **[FILL IN: Practice]**
   - [Why it matters]

## Common Pitfalls

### Pitfall 1: [FILL IN: Name]
**How to avoid:** [Solution]

## Related Skills

- **[related-skill]**: [Relationship]
EOF

echo "Created skill: $SKILL_FILE"
echo "Created directories:"
echo "  - ${SKILL_DIR}/templates/"
echo "  - ${SKILL_DIR}/examples/"
echo ""
echo "Please edit and fill in the [FILL IN: ...] placeholders"

Best Practices Summary

For Subagents

1. Single Responsibility: One clear, focused purpose
2. Tool Minimalism: Only grant necessary tools
3. Clear Descriptions: Keyword-rich, specific, 20+ words
4. Explicit Output: Define exact format in system prompt
5. Appropriate Proactivity: Most agents should be proactive: false
6. Comprehensive Prompts: Role, responsibilities, guidelines, constraints, examples

For Skills

1. Clear Instructions: Step-by-step, actionable guidance
2. Comprehensive Examples: Both good and bad with explanations
3. Focused Scope: One domain/topic per skill, under 500 lines
4. Supporting Files: Templates, examples, scripts well-organized
5. Best Practices: Document "why" not just "what"
6. Common Pitfalls: Show mistakes and how to avoid them

Quality Checklist

Before Creating an Agent

• Is a subagent the right tool? (vs skill or just asking Claude)
• Is the scope focused enough? (single responsibility)
• Have I minimized the tool set?
• Is the description clear and keyword-rich?
• Is the output format explicitly defined?
• Have I included examples in the system prompt?
• Are constraints clearly stated?

Before Creating a Skill

• Is a skill the right tool? (vs subagent)
• Is the scope focused enough? (one domain/topic)
• Are instructions step-by-step and actionable?
• Do I have comprehensive examples (good & bad)?
• Are supporting files needed and created?
• Are best practices documented?
• Are common pitfalls covered?
• Is it under 500 lines? (if not, should it be split?)

Quick Reference Commands

# List all agents
ls -1 .claude/agents/

# List all skills
ls -1 .claude/skills/

# Create new agent (using template script)
./templates/create-agent.sh my-agent analyzer

# Create new skill (using template script)
./templates/create-skill.sh my-skill conventions

# View agent
cat .claude/agents/agent-name.md

# View skill
cat .claude/skills/skill-name/SKILL.md

Related Agents

• agent-builder: Uses these templates to create new agents
• skill-builder: Uses these templates to create new skills
• agent-skill-analyzer: Uses these templates as quality benchmarks

Remember: These templates are starting points. Customize them for your specific use case while maintaining the core structure and best practices.

Version: 1.0 Last Updated: 2025-12-19