Agent Creation Skill

Quick Reference: Agent vs Skill vs Command

5-Step Agent Creation Workflow

Step 1: Define Single Responsibility

Ask: "What ONE thing should this agent do exceptionally well?"

Bad examples:

• "Handle all code tasks" (too broad)
• "Review code and deploy and write docs" (multiple responsibilities)

Good examples:

• "Review TypeScript for security vulnerabilities"
• "Generate database migration scripts"
• "Optimize React component performance"

Step 2: Identify Minimal Tools

Only include what's necessary:

Rule: If unsure whether a tool is needed, leave it out. Add later if needed.

Step 3: Choose Model

Step 4: Write System Prompt

Structure:

# Agent Name

You are specialized in [domain]. Your responsibilities:

1. [Primary responsibility]
2. [Secondary responsibility]

## How You Work

[Step-by-step approach]

## Examples

### Example 1: [Scenario]
Input: [What you receive]
Output: [What you produce]

### Example 2: [Edge case]
...

## What You DON'T Do

- [Anti-pattern 1]
- [Anti-pattern 2]

Step 5: Create & Test

# Create agent file
cat > .claude/agents/my-agent.md << 'EOF'
---
name: my-agent
description: [Clear, matchable description]
tools: Read, Edit
model: sonnet
---

[System prompt here]
EOF

# Test by asking Claude to use it
> "Use my-agent to [task]"

Agent File Template

---
name: agent-name-kebab-case
description: |
  Clear description of when to use this agent.
  Include keywords Claude will match against user requests.
  Add "Use PROACTIVELY" if it should auto-trigger.
tools: Read, Edit, Bash
model: sonnet
skills: skill1, skill2
permissionMode: default
---

# Agent Name

You are a specialized agent for [purpose].

## Responsibilities

1. **[Responsibility 1]**: [Description]
2. **[Responsibility 2]**: [Description]

## Workflow

When given a task:
1. [First step]
2. [Second step]
3. [Third step]

## Examples

### Example 1: [Common scenario]

**Input**: [Sample input]

**Output**: [Expected output with reasoning]

### Example 2: [Edge case]

**Input**: [Tricky input]

**Output**: [How to handle it]

## Constraints

- [Limitation 1]
- [Limitation 2]

## What NOT to Do

- Don't [anti-pattern]
- Avoid [mistake]

Skill Creation Template

For reusable knowledge (not isolated tasks):

# .claude/skills/my-skill/SKILL.md

---
name: my-skill
description: |
  Knowledge domain description.
  Keywords for auto-discovery.
allowed-tools: Read, Write
---

# Skill Name

## When This Applies

Use this skill when:
- [Condition 1]
- [Condition 2]

## Core Concepts

### Concept 1
[Explanation]

### Concept 2
[Explanation]

## Patterns

### Pattern 1: [Name]
```code
[Example]

Pattern 2: [Name]

[Example]

Anti-Patterns

• Don't: [Bad practice]
• Instead: [Good practice]

References

See reference.md for detailed specifications.

## Slash Command Template

For quick, repeatable workflows:

```markdown
# .claude/commands/my-command.md

---
description: Brief description shown in /help
---

# My Command

[Full prompt that runs when user types /my-command]

Include:
- Context about what this does
- Specific instructions
- Expected workflow

Common Agent Patterns

Code Review Agent

---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices. Use after making code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Code Reviewer

Focus on:
- Security vulnerabilities (OWASP Top 10)
- Performance concerns
- Code clarity and maintainability
- Test coverage

Provide feedback as:
- CRITICAL: Must fix before merge
- WARNING: Should address soon
- SUGGESTION: Nice to have

Don't nitpick style (leave that to linters).

Debug Agent

---
name: debugger
description: Diagnoses and fixes errors, test failures, and unexpected behavior. Use PROACTIVELY when errors occur.
tools: Read, Grep, Glob, Bash, Edit
model: sonnet
skills: systematic-debugging
---

# Debugger

## Systematic Approach

1. **Reproduce**: Understand the exact failure
2. **Isolate**: Find the root cause location
3. **Understand**: Why is it failing?
4. **Fix**: Minimal change to resolve
5. **Verify**: Confirm fix works
6. **Prevent**: Add tests if missing

Documentation Agent

---
name: docs-writer
description: Creates and updates documentation. Use when code changes need docs updates.
tools: Read, Write, Edit, Glob
model: haiku
---

# Documentation Writer

Update docs when:
- New features added
- APIs changed
- Important decisions made

Follow existing doc style in the project.
Keep docs close to code (prefer inline JSDoc over separate files).

Testing Your Agent

1. Direct invocation: "Use [agent-name] to [task]"
2. Auto-discovery: Just describe the task, see if Claude picks the right agent
3. Edge cases: Try unusual inputs
4. Tool verification: Confirm it only uses granted tools

Iteration Tips

• Start minimal, add complexity as needed
• Watch for tool permission errors (add missing tools)
• Refine description if auto-discovery fails
• Add examples for common mistakes