agent-design-best-practices_skill

Overview

This skill codifies best practices for designing Claude Code agent files (.claude/agents/*.md). It helps authors create reusable, focused agent definitions that describe capabilities rather than hardcode lifecycle or workflow phases. The guidance blends Anthropic's official recommendations with practical patterns proven by agent teams.

How this skill works

The skill inspects agent YAML frontmatter and the markdown body to ensure descriptions are specific, tools are minimal, and the agent defines domain expertise not execution timing. It checks for anti-patterns like phase-coupled agents, hardcoded interaction protocols, overly broad or overly narrow domains, and unsafe tool grants. It also enforces a clear body structure: role statement, analysis process, output format, and constraints.

When to use it

• When authoring a new .claude/agents/*.md agent file to ensure correct structure and focus.
• When reviewing existing agent files to remove workflow coupling or excessive tool permissions.
• Before committing agent changes to confirm description, tools, and output formats meet standards.
• When converting multiple phase-specific agents into a single domain-focused agent.
• When auditing team agent teams for file ownership and context-window isolation issues.

Best practices

• Define capabilities, not lifecycle: describe what the agent can do; leave timing and instructions to the spawn prompt.
• One agent per domain: prefer a single specialist over multiple phase-split agents; spawn with different prompts for phases.
• Be specific in YAML description: include triggers and the agent’s area of expertise so Claude can delegate appropriately.
• Limit tool access to the minimal set needed for the domain (e.g., Read/Grep for reviewers; add Write/Edit only for implementers).
• Avoid hardcoding communication patterns; define output formats but let the team lead handle delivery and input mechanics.
• Include enough domain knowledge for independent operation and design file ownership to avoid overlapping edit scopes.

Example use cases

• Create a security-specialist agent that performs STRIDE threat modeling and OWASP checks usable in planning and review.
• Refactor two phase-specific test agents into one test-specialist that can be spawned for planning or coverage tasks.
• Review an agent file to remove 'SendMessage' or phase references and constrain tools to read-only for reviewers.
• Audit team agents to ensure teammates own distinct file sets (implementer -> src/, tester -> tests/).
• Set frontmatter fields: clear description, minimal tools, optional model only when justified, and appropriate permissionMode.