agent-builder

Agent Builder - Claude Code Subagent Expert

Use this skill when creating, improving, or troubleshooting Claude Code subagents. Provides expert guidance on agent design, system prompt engineering, tool configuration, and delegation patterns.

When to Use This Skill

Activate this skill when:

• User asks to create a new subagent
• User wants to improve an existing agent
• User needs help with agent configuration or tool access
• User is troubleshooting agent invocation issues
• User wants to understand when to use agents vs skills vs commands
• User asks about agent chaining or delegation patterns

Quick Reference

Agent File Structure

---
name: agent-name
description: When and why to use this agent
tools: Read, Write, Bash(git *)
model: sonnet
---

Your detailed system prompt defining:
- Agent role and expertise
- Problem-solving approach
- Output format expectations
- Specific constraints or requirements

File Locations

Project agents (shared with team, highest priority):

.claude/agents/my-agent.md

Personal agents (individual use, lower priority):

~/.claude/agents/my-agent.md

Plugin agents (from installed plugins):

<plugin-dir>/agents/agent-name.md

Creating Effective Subagents

Step 1: Identify the Use Case

Good candidates for subagents:

• Complex, multi-step workflows
• Specialized expertise (debugging, security review, data analysis)
• Tasks requiring focused context
• Repeatable processes with specific quality bars
• Code review and analysis workflows

NOT good for subagents (use Skills/Commands instead):

• Simple one-off prompts (use Slash Commands)
• Context-aware automatic activation (use Skills)
• Quick transformations or formatting

Step 2: Design Agent Scope

Best practices:

• Single responsibility - Each agent does ONE thing exceptionally well
• Clear boundaries - Define what's in/out of scope
• Specific expertise - Don't create "general helper" agents
• Measurable outcomes - Agent should produce concrete deliverables