creating-claude-agents
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.
AgentWorkforce · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add AgentWorkforce/relay --skill creating-claude-agentsAbout this 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 decisionshaiku- Fast, simple tasksinherit- 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 |