Creating Claude Agents

If you're building Claude Code agents and keep running into validation errors or aren't sure what goes in the frontmatter versus the content, this walks you through the whole structure. It covers the schema requirements (name patterns, field limits, tool permissions), explains when to use sonnet versus opus versus haiku, and shows you how to write the persona definition and process steps. The quick reference alone is worth having open when you're editing agent markdown files. One thing to know: it's pretty strict about the format (lowercase-and-hyphens naming, specific H1 requirements), but that's because the tooling enforces a schema, so better to get it right the first time.

GitHub stars: 719
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add agentworkforce/relay --skill creating-claude-agents --agent claude-code

Installs into .claude/skills of the current project.

Files

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]