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

   • Check each category (quality, security, performance)
   • Provide specific file:line references
   • Explain why something is an issue

3. Provide actionable feedback

   • Categorize by severity
   • Include fix suggestions
   • Highlight positive patterns

4. Include Examples

Show both good and bad patterns:

Examples

When reviewing error handling:

❌ Bad - Silent failure: ```typescript try { await fetchData(); } catch (error) { console.log(error); } ```

✅ Good - Proper error handling: ```typescript try { await fetchData(); } catch (error) { logger.error('Failed to fetch data', error); throw new AppError('Data fetch failed', { cause: error }); } ```

5. Use Icons in H1 for Visual Distinction

Choose emojis that represent the agent's purpose:

• 🔍 Code Reviewer

• 🐛 Debugger

• 📊 Data Scientist

• 🔒 Security Auditor

• ⚡ Performance Optimizer

• 📝 Documentation Writer

• 🧪 Test Generator

6. Maintain Single Responsibility

Each agent should excel at ONE specific task:

✅ Good:

• code-reviewer

• Reviews code for quality and security

• debugger

• Root cause analysis and minimal fixes

❌ Poor:

• code-helper
• Reviews, debugs, tests, refactors, documents (too broad)

7. Grant Minimal Tool Access

Follow the principle of least privilege:

Read-only analysis agent

allowed-tools: Read, Grep

Code modification agent

allowed-tools: Read, Edit, Bash(git *)

Full development agent

allowed-tools: Read, Write, Edit, Bash, Grep, Glob

8. Include agentType for Round-Trip Conversion

Always include agentType: agent in frontmatter to preserve type information during format conversions:

name: code-reviewer description: Reviews code for best practices agentType: agent

Example Agent Templates

Minimal Agent

name: simple-reviewer description: Quick code review for common issues allowed-tools: Read, Grep model: haiku agentType: agent

🔍 Simple Code Reviewer

You are a code reviewer focused on catching common mistakes quickly.

Instructions

Review code for:

• Syntax errors
• Common anti-patterns
• Missing error handling
• Console.log statements

Provide concise feedback with file:line references.

Comprehensive Agent

name: security-auditor description: Deep security vulnerability analysis for code changes allowed-tools: Read, Grep, WebSearch, Bash(git *) model: opus agentType: agent

🔒 Security Auditor

You are a security expert specializing in application security, with expertise in OWASP Top 10, secure coding practices, and threat modeling. You perform thorough security analysis of code changes.

Review Process

1. Gather Context

   • Read changed files
   • Review git history for context
   • Identify data flows and trust boundaries

2. Security Analysis

   • Input validation and sanitization
   • Authentication and authorization
   • SQL injection risks
   • XSS vulnerabilities
   • CSRF protection
   • Secrets exposure
   • Cryptography usage
   • Dependency vulnerabilities

3. Threat Assessment

   • Rate severity (Critical/High/Medium/Low)
   • Assess exploitability
   • Determine business impact
   • Provide remediation guidance

4. Report Findings Use structured format with CVE references where applicable.

Output Format

Security Score: X/10

Critical Issues (Fix Immediately)

• [Vulnerability] (file:line) - [Explanation] - [CVE if applicable] - [Fix]

High Priority

• [Issue] (file:line) - [Explanation] - [Fix]

Medium Priority

• [Concern] (file:line) - [Explanation] - [Recommendation]

Best Practices

• [Positive security pattern observed]

Recommendation: [Approve/Request Changes/Block]

Examples

SQL Injection Check

❌ Vulnerable: ```typescript const query = `SELECT * FROM users WHERE id = ${userId}`; db.query(query); ```

✅ Safe: ```typescript const query = 'SELECT * FROM users WHERE id = $1'; db.query(query, [userId]); ```

Validation Checklist

Before finalizing an agent:

• Name is lowercase with hyphens only

• Name is 64 characters or less

• Description clearly explains when to use the agent

• Description is 1024 characters or less

• Content starts with H1 heading (with emoji icon)

• Persona is defined using "You are..." format

• Process or instructions are clearly outlined

• Examples are included (showing good/bad patterns)

• Tool access is minimal and specific

• Model selection is appropriate for task complexity

• agentType field is set to "agent"

• File is saved in .claude/agents/ directory

• Agent has been tested with real tasks

• Edge cases are considered

Schema Reference

Official Schema URL:

https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json

Local Schema Path:

/Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/claude-agent.schema.json

Related Documentation

• agent-builder skill - Creating effective subagents

• slash-command-builder skill - For simpler, command-based prompts

• creating-skills skill - For context-aware reference documentation

• Claude Code Docs: https://docs.claude.com/claude-code

Agents vs Skills vs Commands

Use Agents When:

• ✅ Long-running assistants with persistent context

• ✅ Complex multi-step workflows

• ✅ Specialized expertise needed

• ✅ Tool access required

• ✅ Repeatable processes with quality standards

Use Skills When:

• ✅ Context-aware automatic activation

• ✅ Reference documentation and patterns

• ✅ Team standardization

• ✅ No persistent state needed

Use Slash Commands When:

• ✅ Simple, focused prompts

• ✅ Quick manual invocation

• ✅ Personal productivity shortcuts

• ✅ Single-file prompts

Decision Tree:

Need specialized AI assistant? ├─ Yes → Needs tools and persistent context? │ ├─ Yes → Use Agent │ └─ No → Quick invocation? │ ├─ Yes → Use Slash Command │ └─ No → Use Skill └─ No → Just documentation? → Use Skill

Troubleshooting

Agent Not Activating

Problem: Agent doesn't get invoked when expected

Solutions:

• Make description more specific to match use case

• Verify file is in .claude/agents/*.md

• Check for frontmatter syntax errors

• Explicitly request: "Use the [agent-name] agent"

Validation Errors

Problem: Agent file doesn't validate against schema

Solutions:

• Check name pattern (lowercase, hyphens only)

• Verify required fields (name, description)

• Ensure content starts with H1 heading

• Validate model value is in enum

• Check allowed-tools spelling and capitalization

Tool Permission Denied

Problem: Agent can't access needed tools

Solutions:

• Add tools to allowed-tools in frontmatter

• Use correct capitalization (e.g., Read , not read )

• For Bash restrictions, use pattern syntax: Bash(git *)

• Omit allowed-tools field to inherit all tools

Poor Agent Performance

Problem: Agent produces inconsistent or low-quality results

Solutions:

• Strengthen persona definition

• Add more specific process steps

• Include examples of good/bad patterns

• Define explicit output format

• Consider using more powerful model (opus)

• Break complex agents into specialized ones

Remember: Great agents are specialized experts with clear personas, step-by-step processes, and minimal tool access. Focus each agent on doing ONE thing exceptionally well with measurable outcomes.