Initial commit

skills/agent-builder/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: agent-builder
+description: Create custom Claude Code sub-agents with specialized expertise and tool access. Use when you need to build reusable agents for specific tasks like code review, debugging, data analysis, or domain-specific workflows.
+version: 1.0.0
+---
+
+# Build Custom Claude Code Sub-Agents
+
+## When to Use
+
+- Creating a specialized agent for recurring tasks (code review, debugging, testing)
+- Need an agent with specific tool permissions or limited scope
+- Want to share reusable agents across projects or with your team
+- Building domain-specific agents (data science, DevOps, security)
+- Need to preserve main conversation context while delegating complex tasks
+
+## What This Skill Does
+
+Guides you through creating custom sub-agents that:
+
+- **Specialize**: Focused expertise for specific domains or tasks
+- **Isolate**: Separate context windows prevent main conversation pollution
+- **Reuse**: Deploy across projects and share with teams
+- **Control**: Granular tool access and model selection per agent
+
+## Quick Start
+
+### 1. Use the Built-In Agent Creator
+
+```bash
+# Run the agents command
+/agents
+```
+
+Then:
+1. Select "Create New Agent"
+2. Choose project-level (`.claude/agents/`) or user-level (`~/.claude/agents/`)
+3. Generate with Claude or manually define configuration
+4. Save and test
+
+### 2. Manual Agent Creation
+
+Create a markdown file in `.claude/agents/` (project) or `~/.claude/agents/` (user):
+
+```markdown
+---
+name: my-agent-name
+description: Use this agent when [specific trigger condition]
+tools: Read, Edit, Bash
+model: sonnet
+---
+
+# Agent System Prompt
+
+Your detailed instructions for the agent go here.
+
+Be specific about:
+- What tasks this agent handles
+- How to approach problems
+- What outputs to produce
+- Any constraints or guardrails
+```
+
+### 3. Invoke Your Agent
+
+**Automatic**: Claude detects matching tasks based on description
+**Explicit**: "Use the my-agent-name agent to [task]"
+
+## Agent Configuration
+
+### Required Fields
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `name` | Lowercase with hyphens | `code-reviewer` |
+| `description` | When to use this agent (triggers routing) | `Use PROACTIVELY to review code changes for quality and security` |
+
+### Optional Fields
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `tools` | Comma-separated tool list | All tools inherited |
+| `model` | Model alias (sonnet/opus/haiku) or 'inherit' | Inherits from main |
+
+**See**: [Configuration Reference](./reference/configuration-guide.md)
+
+## Agent Structure
+
+```
+.claude/agents/           # Project-level agents
+├── code-reviewer.md
+├── debugger.md
+└── custom-agent.md
+
+~/.claude/agents/         # User-level agents (global)
+├── my-helper.md
+└── data-analyzer.md
+```
+
+**Priority**: Project agents override user agents with same name
+
+## Common Agent Types
+
+### Code Reviewer
+Reviews code for quality, security, and best practices
+
+**Triggers**: After code changes, before commits
+
+### Debugger
+Analyzes errors, identifies root causes, proposes fixes
+
+**Triggers**: Test failures, runtime errors
+
+### Data Scientist
+Writes SQL queries, performs analysis, generates reports
+
+**Triggers**: Data questions, BigQuery tasks
+
+**See**: [Agent Examples](./reference/agent-examples.md)
+
+## Best Practices
+
+1. **Single Responsibility**: One focused task per agent
+2. **Descriptive Triggers**: Use "PROACTIVELY" or "MUST BE USED" for automatic delegation
+3. **Detailed Prompts**: Specific instructions yield better results
+4. **Limit Tools**: Only grant necessary permissions
+5. **Version Control**: Commit project agents for team collaboration
+
+**Full Guide**: [Best Practices](./reference/best-practices.md)
+
+## Available Tools
+
+Sub-agents can access:
+- **File Operations**: Read, Write, Edit, Glob, Grep
+- **Execution**: Bash
+- **MCP Tools**: Any installed MCP server tools
+
+Use `/agents` interface to visually select tools.
+
+## Outputs
+
+This skill helps you create:
+- Agent configuration files (`.md` with YAML frontmatter)
+- Specialized system prompts
+- Tool permission configurations
+- Reusable agent templates
+
+## Guardrails
+
+- Agents must have focused, well-defined purposes
+- Use lowercase-with-hyphens naming convention
+- Always specify clear trigger conditions in description
+- Grant minimal tool access (principle of least privilege)
+- Test agents thoroughly before sharing with team
+
+## Advanced Topics
+
+- [Configuration Guide](./reference/configuration-guide.md) - Complete field reference
+- [Agent Examples](./reference/agent-examples.md) - Real-world templates
+- [Best Practices](./reference/best-practices.md) - Design patterns
+- [Troubleshooting](./reference/troubleshooting.md) - Common issues
+
+## Triggers
+
+This skill activates when you mention:
+- "create an agent" or "build an agent"
+- "sub-agent" or "subagent"
+- "agent configuration"
+- "Task tool" or "custom agent"
+- "agent best practices"
+
+## Testing
+
+To test your agent:
+
+```bash
+# Ask Claude to use it explicitly
+"Use the [agent-name] agent to [task]"
+
+# Or test automatic triggering
+"[Describe a task matching agent's description]"
+```
+
+Verify:
+- [ ] Agent triggers correctly
+- [ ] Has necessary tool access
+- [ ] Produces expected outputs
+- [ ] Maintains scope/focus
+
+---
+
+**Last Updated**: 2025-10-27
+**Version**: 1.0.0