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.
SkillScore95Maintained
Automatic
◆AI Engineer pack
Last verified 8/19/2026
What it changes
Passed 21 of 22 test cases with the skill, and 4 of 22 without it.
Without skill18%
With skill95%
Checks it passed that the model alone missed
Formats allowed-tools as a comma-separated string
Frontmatter specifies model as opus for complex reasoning tasks
Requires the persona statement to begin with the phrase You are
and 22 more in the full report
17 fixed4 passed either way1 still failing0 broke
Pass-rate lift
+77 pp
Tokens
+155%
Agent turns
0%
Response time
-41%
Model gemini-3.6-flashMeasured 8/19/2026v121 of 22 cases passed with skill
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 17 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 17
Prompt
I am drafting the content section of an agent markdown file for `debug-assistant`. What is the required first line of content immediately following the frontmatter YAML block according to agent formatting standards?
What was checked, without and with the skill
Checked
Without skill
With skill
Requires the content to begin with an H1 heading as the first line after frontmatter
Passed
Passed
Recommends including an emoji icon in the H1 title for visual distinction
Missed
Passed
case-14 · gemini-3.6-flash · 8/19/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md631 linessingle file
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