simplerick0/claude-agents

Claude Code Subagents

Create specialized AI subagents that handle specific types of tasks with isolated context, custom tools, and focused system prompts.

File Structure

Subagents are Markdown files with YAML frontmatter stored in:

• .claude/agents/ - Project-level (check into version control)
• ~/.claude/agents/ - User-level (available in all projects)

Frontmatter Fields

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Lowercase letters and hyphens only | | description | Yes | When Claude should delegate (include "use proactively" for automatic use) | | tools | No | Tools to allow (inherits all if omitted) | | disallowedTools | No | Tools to deny | | model | No | sonnet, opus, haiku, or inherit (default: inherit) | | permissionMode | No | default, acceptEdits, dontAsk, bypassPermissions, plan | | skills | No | Skills to preload into subagent context | | hooks | No | Lifecycle hooks for this subagent |

Available Tools

Read-only: Read, Glob, Grep, WebFetch, WebSearch Modification: Write, Edit, NotebookEdit Execution: Bash, Task Other: AskUserQuestion, Skill, mcp__* (MCP tools)

Template

---
name: my-agent
description: Brief description of purpose. Use proactively when [trigger conditions].
tools: Read, Glob, Grep, Bash
model: sonnet
skills:
  - relevant-skill-name
---

You are a [role] responsible for [responsibilities].

## When Invoked

1. [First step]
2. [Second step]
3. [Continue as needed]

## Key Practices

- [Practice 1]
- [Practice 2]

## Output Format

[Describe expected output structure]

Best Practices

1. Focus on one task - Each subagent should excel at a specific purpose
2. Write detailed descriptions - Claude uses this to decide when to delegate
3. Limit tool access - Grant only necessary permissions for security
4. Preload relevant skills - Use skills field for domain knowledge
5. Include trigger phrases - Add "use proactively" for automatic delegation
6. Specify model wisely - Use haiku for fast/cheap, sonnet for balanced, opus for complex

Model Selection

| Model | Use When | |-------|----------| | haiku | Fast exploration, simple validation, high-volume operations | | sonnet | Balanced capability and speed, code analysis, most tasks | | opus | Complex reasoning, architecture decisions, nuanced analysis | | inherit | Match parent conversation model |

Tool Restriction Patterns

Read-only Agent

tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit

Code Modification Agent

tools: Read, Write, Edit, Bash, Glob, Grep

Research Agent

tools: Read, Glob, Grep, WebFetch, WebSearch

Hooks

Subagents can define hooks in frontmatter:

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/lint.sh"

Common Patterns

Isolate Verbose Output

Delegate test runs, log analysis, or documentation fetching to subagents to keep main context clean.

Parallel Research

Spawn multiple subagents for independent investigations, then synthesize results.

Chain Subagents

Use subagents in sequence: reviewer → optimizer → validator.