Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →majiayu000/agent-design-best-practices
Best practices for designing Claude Code agent files (.claude/agents/*.md). This skill should be used when writing or reviewing agent markdown files to ensure proper design with focused domains, correct tool access, reusable definitions, and separation of capabilities from lifecycle. Combines Anthropic's official guidance with battle-tested patterns from agent team usage.
Passed 21 of 22 test cases with the skill, and 14 of 22 without it.
and 5 more in the full report
7 fixed14 passed either way1 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 7 test cases the skill fixed. Same model, same prompt, with and without the skill.
What are the minimal required YAML frontmatter fields for defining a Claude Code agent file in `.claude/agents/`?
| Checked | Without skill | With skill |
|---|---|---|
| The response lists name, description, and tools as the essential frontmatter keys. | Missed | Passed |
The instructions your model reads when the skill loads.
This skill defines best practices for designing Claude Code agent files (.claude/agents/*.md). Agent files define reusable roles that can be spawned as subagents or teammates. The core principle is that agent files define capabilities, not lifecycle -- the team lead's spawn prompt controls when and how the agent runs.
Agent files describe what an agent can do. The spawn prompt from the team lead controls when it runs and what to focus on.
<!-- Wrong: Hardcodes workflow phase and interaction pattern -->
# Security Planner Agent
You are a security specialist in a plan-create Agent Team.
Given a Research Brief from the team lead, identify security
considerations for the planned changes.
## Output Format
Send your sub-plan to the team lead via `SendMessage` with this structure:
...
<!-- Correct: Defines domain expertise, team lead controls usage -->
# Security Specialist Agent
You are a security specialist who identifies vulnerabilities,
evaluates threats, and recommends mitigations for code changes.
## Analysis Process
1. Read affected files
2. STRIDE analysis
3. Check input validation
...
test cases passed, vs 14 / 22 without
Published skills whose descriptions closely match this one, with their headline benchmark lift.
More skills from the same source and nearby in the registry, with their headline benchmark lift.