creating-claude-agents

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

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

# 🔍 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:

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

# 🔍 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

{
  "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:

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

Specific Tools Only

Grant minimal necessary permissions:

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

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

model: sonnet

Opus (Complex Reasoning)

Use for:

• Architecture decisions
• Complex refactoring
• Deep security analysis
• Novel problem-solving

model: opus

Haiku (Speed Matters)

Use for:

• Syntax checks
• Simple formatting
• Quick validations
• Low-latency needs

model: haiku

Inherit (Context-Dependent)

Use for:

• Agent should match user's model choice
• Cost sensitivity

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:

description: Reviews code changes for quality, security, and maintainability issues

❌ Poor:

description: A helpful agent  # Too vague

2. Define Strong Personas

Establish expertise and approach immediately after the H1:

# 🔍 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:

## Review Process

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

2. **Analyze systematically**
   - Ch