/creating-claude-agents-skill

name: creating-claude-agents
description: Use when creating or improving Claude Code agents. Expert guidance on agent file structure, frontmatter, persona definition, tool access, model selection, and validation against schema.

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 |

T