creating-claude-agents

What this skill does

# Creating Claude Code Agents - Expert Skill

Use this skill when creating or improving Claude Code agents. Provides comprehensive guidance on agent structure, schema validation, and best practices for building long-running AI assistants.

## When to Use This Skill

Activate this skill when:
- User asks to create a new Claude Code agent
- User wants to improve an existing agent
- User needs help with agent frontmatter or structure
- User is troubleshooting agent validation issues
- User wants to understand agent format requirements
- User asks about agent vs skill vs slash command differences

## Quick Reference

### Agent File Structure

```markdown
---
name: agent-name
description: When and why to use this agent
allowed-tools: Read, Write, Bash
model: sonnet
agentType: agent
---

# 🔍 Agent Display Name

You are [persona definition - describe the agent's role and expertise].

## Instructions

[Clear, actionable guidance on what the agent does]

## Process

[Step-by-step workflow the agent follows]

## Examples

[Code samples and use cases demonstrating the agent's capabilities]
```

### File Location

**Required Path:**
```
.claude/agents/*.md
```

Agents must be placed in `.claude/agents/` directory as markdown files.

## Frontmatter Requirements

### Required Fields

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `name` | string | Agent identifier (lowercase, hyphens only) | `code-reviewer` |
| `description` | string | Brief overview of functionality and use cases | `Reviews code for best practices and potential issues` |

### Optional Fields

| Field | Type | Description | Values |
|-------|------|-------------|--------|
| `allowed-tools` | string | Comma-separated list of available tools | `Read, Write, Bash, WebSearch` |
| `model` | string | Claude model to use | `sonnet`, `opus`, `haiku`, `inherit` |
| `agentType` | string | Explicit marker for format preservation | `agent` |

### Validation Rules

**Name Field:**
- Pattern: `^[a-z0-9-]+$` (lowercase letters, numbers, hyphens only)
- Max length: 64 characters
- Example: ✅ `code-reviewer` ❌ `Code_Reviewer`

**Description Field:**
- Max length: 1024 characters
- Should clearly explain when to use the agent
- Start with action words: "Reviews...", "Analyzes...", "Helps with..."

**Allowed Tools:**
Valid tools: `Read`, `Write`, `Edit`, `Grep`, `Glob`, `Bash`, `WebSearch`, `WebFetch`, `Task`, `Skill`, `SlashCommand`, `TodoWrite`, `AskUserQuestion`

**Model Values:**
- `sonnet` - Balanced, good for most agents (default)
- `opus` - Complex reasoning, architectural decisions
- `haiku` - Fast, simple tasks
- `inherit` - Use parent conversation's model

## Content Format Requirements

### H1 Heading (Required)

The first line of content must be an H1 heading that serves as the agent's display title:

```markdown
# 🔍 Code Reviewer
```

**Best Practices:**
- Include an emoji icon for visual distinction
- Use title case
- Keep concise (2-5 words)
- Make it descriptive and memorable

### Persona Definition (Required for Agents)

Immediately after the H1, define the agent's persona using "You are..." format:

```markdown
You are an expert code reviewer with deep knowledge of software engineering principles and security best practices.
```

**Guidelines:**
- Start with "You are..."
- Define role and expertise clearly
- Set expectations for the agent's capabilities
- Establish the agent's approach and tone

### Content Structure

```markdown
# 🔍 Agent Name

You are [persona definition].

## Instructions

[What the agent does and how it approaches tasks]

## Process

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Examples

[Code samples showing good/bad patterns]

## Guidelines

- [Best practice 1]
- [Best practice 2]
```

## Schema Validation

Agents must conform to the JSON schema at:
`https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json`

### Schema Structure

```json
{
  "frontmatter": {
    "name": "string (required)",
    "description": "string (required)",
    "allowed-tools": "string (optional)",
    "model": "enum (optional)",
    "agentType": "agent (optional)"
  },
  "content": "string (markdown with H1, persona, instructions)"
}
```

### Common Validation Errors

| Error | Cause | Fix |
|-------|-------|-----|
| Missing required field 'name' | Frontmatter lacks name field | Add `name: agent-name` |
| Missing required field 'description' | Frontmatter lacks description | Add `description: ...` |
| Invalid name pattern | Name contains uppercase or special chars | Use lowercase and hyphens only |
| Name too long | Name exceeds 64 characters | Shorten the name |
| Invalid model value | Model not in enum | Use: `sonnet`, `opus`, `haiku`, or `inherit` |
| Missing H1 heading | Content doesn't start with # | Add `# Agent Name` as first line |

## Tool Configuration

### Inheriting All Tools

Omit the `allowed-tools` field to inherit all tools from the parent conversation:

```yaml
---
name: full-access-agent
description: Agent needs access to everything
# No allowed-tools field = inherits all
---
```

### Specific Tools Only

Grant minimal necessary permissions:

```yaml
---
name: read-only-reviewer
description: Reviews code without making changes
allowed-tools: Read, Grep, Bash
---
```

### Bash Tool Restrictions

Use command patterns to restrict Bash access:

```yaml
---
name: git-helper
description: Git operations only
allowed-tools: Bash(git *), Read
---
```

**Syntax:**
- `Bash(git *)` - Only git commands
- `Bash(npm test:*)` - Only npm test scripts
- `Bash(git status:*)`, `Bash(git diff:*)` - Multiple specific commands

## Model Selection Guide

### Sonnet (Most Agents)

**Use for:**
- Code review
- Debugging
- Data analysis
- General problem-solving

```yaml
model: sonnet
```

### Opus (Complex Reasoning)

**Use for:**
- Architecture decisions
- Complex refactoring
- Deep security analysis
- Novel problem-solving

```yaml
model: opus
```

### Haiku (Speed Matters)

**Use for:**
- Syntax checks
- Simple formatting
- Quick validations
- Low-latency needs

```yaml
model: haiku
```

### Inherit (Context-Dependent)

**Use for:**
- Agent should match user's model choice
- Cost sensitivity

```yaml
model: inherit
```

## Common Mistakes

| Mistake | Problem | Solution |
|---------|---------|----------|
| Using `_` in name | Violates pattern constraint | Use hyphens: `code-reviewer` not `code_reviewer` |
| Uppercase in name | Violates pattern constraint | Lowercase only: `debugger` not `Debugger` |
| Missing persona | Agent lacks role definition | Add "You are..." after H1 |
| No H1 heading | Content format invalid | Start content with `# Agent Name` |
| Vague description | Agent won't activate correctly | Be specific about when to use |
| Too many tools | Security risk, violates least privilege | Grant only necessary tools |
| No agentType field | May lose type info in conversion | Add `agentType: agent` |
| Generic agent name | Conflicts or unclear purpose | Use specific, descriptive names |

## Best Practices

### 1. Write Clear, Specific Descriptions

The description determines when Claude automatically invokes your agent.

✅ **Good:**
```yaml
description: Reviews code changes for quality, security, and maintainability issues
```

❌ **Poor:**
```yaml
description: A helpful agent  # Too vague
```

### 2. Define Strong Personas

Establish expertise and approach immediately after the H1:

```markdown
# 🔍 Code Reviewer

You are an expert code reviewer specializing in TypeScript and React, with 10+ years of experience in security-focused development. You approach code review systematically, checking for security vulnerabilities, performance issues, and maintainability concerns.
```

### 3. Provide Step-by-Step Processes

Guide the agent's workflow explicitly:

```markdown
## Review Process

1. **Read the changes**
   - Get recent git diff or specified files
   - Understand the context and purpose

2. **Analyze systematically**
   - C