prompt
FreeDesign narrow, reliable Claude Code sub-agents
FreeFree tier
About prompt
A comprehensive guide and prompt template for designing Claude Code sub-agents. It covers when to use sub-agents versus skills versus inline Claude, provides a standardized file format with YAML frontmatter (including name and description fields for routing), and outlines best practices for creating narrow, reliable, and safe sub-agents. Includes examples of common pitfalls such as overly broad or overly narrow agents, and emphasizes proper tool restrictions and context isolation.
Key Features
Provides clear guidelines for when to use sub-agents vs skills vs inline Claude
Defines sub-agent file format with YAML frontmatter (name and description fields)
Includes best practices for designing narrow, reliable, and safe sub-agents
Warns against common pitfalls: too broad, too narrow, over-privileged, context-heavy
Explains routing via the description field for delegation from parent agent
Recommends isolated context windows to avoid polluting parent’s context
Covers project-local and user-local sub-agent file locations
Pros & Cons
Pros
- Clear, actionable guidelines for effective sub-agent design
- Helps avoid common pitfalls like overly broad or overly privileged agents
- Promotes modular, reusable, and maintainable agent architectures
- Free and open source – available as a text file in a public GitHub repository
Cons
- Only applicable to Claude Code’s sub-agent system; not general-purpose
- Requires understanding of Claude Code environment and its agent routing mechanism
- Does not provide pre-built sub-agents, only design guidance
Best For
Creating reusable specialized agents for code review, auditing, planning, or debugging specific problem classesBuilding a library of sub-agents that can be shared across multiple projects or user sessionsDesigning agents for tasks that benefit from isolated context windows and restricted tool sets
FAQ
When should I use a sub-agent instead of a skill?
Use a sub-agent when the task has a clear specialist responsibility, benefits from an isolated context window, is reusable across parent sessions, and can be triggered by a short description match. Use a skill when the work is a recurring workflow the parent itself should perform and context isolation is not required.
What is the file format for a sub-agent?
A sub-agent lives in a Markdown file with YAML frontmatter, placed either at `.claude/agents/<name>.md` (project-local) or `~/.claude/agents/<name>.md` (user-local). The frontmatter includes a `name` (kebab-case) and a `description` (written for the routing model).
What are the common pitfalls in sub-agent design?
A bad sub-agent can be too broad (the parent never knows when to call it), too narrow (duplicates a one-line tool call), over-privileged (has more capabilities than needed), or context-heavy (system prompt drags in unrelated guidance).