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.
npx skills add majiayu000/claude-skill-registry --skill agent-design-best-practices --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Agent Design Best Practices ## Overview 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. ## Principles ### 1. Define Capabilities, Not Lifecycle Agent files describe *what* an agent can do. The spawn prompt from the team lead controls *when* it runs and *what to focus on*. ```markdown <!-- 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: ... ``` ```markdown <!-- 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. STRI
- Overview
- Principles
- 1. Define Capabilities, Not Lifecycle
- 2. One Agent Per Domain, Not Per Phase
- 3. Design Focused Domains
- 4. Write Detailed Descriptions
- 5. Limit Tool Access
- 6. No Hardcoded Interaction Patterns
- 7. Context Window Isolation
- 8. File Ownership in Teams
- Agent File Structure
- Required Frontmatter
- Optional Frontmatter
- Body Structure
What does the agent-design-best-practices skill do?
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.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill agent-design-best-practices --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.