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