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:
[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
---
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:
// [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
---
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
[Domain] Consultation
Problem Analysis
[What you understand the problem to be]
Key Considerations
- [Consideration 1]
- [Consideration 2]
- [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
- [Action step 1]
- [Action step 2]
- [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
---
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][Command if applicable]
**Expected result:** [What should happen]
1. [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
---
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:**[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
---
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:**[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
---
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:**[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
// 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
- Single Responsibility: One clear, focused purpose
- Tool Minimalism: Only grant necessary tools
- Clear Descriptions: Keyword-rich, specific, 20+ words
- Explicit Output: Define exact format in system prompt
- Appropriate Proactivity: Most agents should be
proactive: false - Comprehensive Prompts: Role, responsibilities, guidelines, constraints, examples
For Skills
- Clear Instructions: Step-by-step, actionable guidance
- Comprehensive Examples: Both good and bad with explanations
- Focused Scope: One domain/topic per skill, under 500 lines
- Supporting Files: Templates, examples, scripts well-organized
- Best Practices: Document "why" not just "what"
- 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.mdRelated 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