Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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

About 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

FieldTypeDescriptionExample
namestringAgent identifier (lowercase, hyphens only)code-reviewer
descriptionstringBrief overview of functionality and use casesReviews code for best practices and potential issues

Optional Fields

FieldTypeDescriptionValues
allowed-toolsstringComma-separated list of available toolsRead, Write, Bash, WebSearch
modelstringClaude model to usesonnet, opus, haiku, inherit
agentTypestringExplicit marker for format preservationagent

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

ErrorCauseFix
Missing required field 'name'Frontmatter lacks name fieldAdd name: agent-name
Missing required field 'description'Frontmatter lacks descriptionAdd description: ...
Invalid name patternName contains uppercase or special charsUse lowercase and hyphens only
Name too longName exceeds 64 charactersShorten the name
Invalid model valueModel not in enumUse: sonnet, opus, haiku, or inherit
Missing H1 headingContent doesn't start with #Add # Agent Name as first line

T

Read the complete source ↗