timequity/subagent-creator

Subagent Creator

Create effective subagents that handle autonomous tasks via the Task tool.

Subagents vs Skills

| Aspect | Subagent | Skill | |--------|----------|-------| | Invocation | Explicit via Task tool | Auto-triggered by context | | Context | Isolated (fresh context window) | Shared with parent | | Complexity | Single .md file | Folder with resources | | Use case | Autonomous discrete tasks | Guidance and procedures | | Nesting | Cannot spawn other subagents | Can reference other skills |

Use subagent when:

• Task is discrete and autonomous
• Fresh context window is beneficial
• Task can run in parallel with other work
• Specialized tool restrictions needed

Use skill when:

• Guidance needed throughout conversation
• Context sharing is important
• Multiple resources (scripts, references) needed

Subagent Structure

agents/
└── agent-name.md
    ├── YAML frontmatter (metadata)
    └── Markdown body (system prompt)

Frontmatter Fields

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Lowercase, hyphens only (e.g., code-reviewer) | | description | Yes | When to use - this triggers dispatch decisions | | tools | No | Comma-separated: Bash, Glob, Grep, Read, Edit, Write | | model | No | sonnet, opus, haiku, or inherit (default: inherit) | | permissionMode | No | default, acceptEdits, bypassPermissions, plan | | skills | No | Comma-separated skills to auto-load |

Tools Reference

Read-only:     Glob, Grep, Read, WebFetch, WebSearch
Write:         Edit, Write, NotebookEdit
Execute:       Bash
All:           * (or omit field)

Permission Modes

| Mode | Description | |------|-------------| | default | Normal permission prompts | | acceptEdits | Auto-accept file edits | | bypassPermissions | Skip all permission prompts | | plan | Plan mode - explore but don't modify |

Writing Effective Prompts

Structure

---
name: agent-name
description: When to use this agent. Be specific about triggers.
tools: Tool1, Tool2
model: sonnet
---

# Agent Name

One-line role description.

## Input Required
What the agent expects to receive.

## Process
Step-by-step what the agent does.

## Output Format
Exact format of the response.

## Rules
- Constraints and boundaries
- What to avoid

Best Practices

1. Be specific about role - First line defines identity
2. Define clear inputs - What must be provided
3. Structure the process - Numbered steps
4. Specify output format - Use code blocks for templates
5. Set boundaries - What NOT to do

Description Guidelines

The description field triggers when the agent is suggested. Include:

• Primary use case
• Required inputs
• Expected output type

# Good
description: Use after completing a task to review code changes. Provide BASE_SHA, HEAD_SHA, and requirements. Returns issues with file:line references.

# Bad
description: Reviews code.

Examples

Minimal Subagent

---
name: summarizer
description: Use to summarize long documents or conversations. Provide the content to summarize.
tools: Read
model: haiku
---

# Summarizer

Summarize the provided content in 3-5 bullet points.

Focus on: key decisions, action items, conclusions.
Skip: greetings, filler, obvious context.

Full Subagent

See references/subagent-examples.md for complete examples.

Creation Process

1. Define the task - What autonomous work does this agent do?
2. Choose tools - Minimum needed (prefer restrictive)
3. Choose model - haiku for simple, sonnet for complex, opus for critical
4. Write prompt - Role, process, output, rules
5. Test - Dispatch via Task tool, iterate

Init Script

scripts/init_subagent.py <agent-name> --path <output-directory>

Creates template agent file with proper structure.

Anti-Patterns

• Too broad - Agent tries to do everything
• Too many tools - Give minimum necessary
• Vague output - Always specify exact format
• No boundaries - Must define what NOT to do
• Wrong model - Don't use opus for simple tasks