subagent-creator

name	subagent-creator
description	Create custom Claude Code subagents with specialized capabilities. Use this skill when users want to create new subagents, customize subagent behavior, or need guidance on subagent design patterns. Triggers include "create a subagent", "make a custom agent", "add a specialized agent", or questions about subagent configuration.

Subagent Creator

Create specialized AI subagents for Claude Code with custom system prompts, tool access, and model selection.

What This Skill Does

This skill helps you create subagent configuration files (.md files) that go in:

• Project-level: .claude/agents/ (specific to current project)
• User-level: ~/.claude/agents/ (available across all projects)

Quick Start

Using /agents Command (Recommended)

The easiest way to create a subagent:

/agents

Select "Create New Agent" → Choose project or user level → Let Claude guide you through configuration.

Manual Creation (Alternative)

Create a file in .claude/agents/ or ~/.claude/agents/:

# Project-level subagent
touch .claude/agents/my-agent.md

# User-level subagent
touch ~/.claude/agents/my-agent.md

Subagent File Format

---
name: agent-name
description: When Claude should use this agent. Be specific about triggers and scenarios.
tools: Read, Write, Edit, Bash  # Optional - omit to inherit all tools
model: haiku  # Optional - omit to use default
---

Your subagent's system prompt goes here.

Define the role, workflow, and guidelines clearly.

Required Fields

• name: Lowercase with hyphens (e.g., code-reviewer, test-runner)
• description: Detailed explanation of when to use this agent (primary trigger mechanism)

Optional Fields

• tools: Comma-separated list. Omit to inherit all tools.
• model: haiku, sonnet, opus, or inherit. Omit for default.
• permissionMode: default, acceptEdits, bypassPermissions, plan, ignore
• skills: Comma-separated skill names to auto-load

Design Your Subagent

Step 1: Choose an Archetype

Read design-patterns.md for detailed patterns:

1. Reviewer - Read-only analysis (code review, security audit)
2. Fixer - Diagnose and repair (debugger, test fixer)
3. Creator - Generate new content (API generator, doc writer)
4. Analyzer - Research and insights (codebase explorer)
5. Executor - Run operations (test runner, deployer)

Step 2: Select a Template

Browse example-templates.md for 10+ ready-to-use templates:

• Code Reviewer
• Debugger
• Test Runner
• Documentation Writer
• Security Auditor
• Performance Optimizer
• Data Analyst
• Deployment Agent
• API Developer
• Refactoring Specialist

Copy and customize for your needs.

Step 3: Write the Description

The description field determines when Claude uses your subagent.

Effective description structure:

[Role]. [Purpose]. Use [trigger] when [scenarios].

Good example:

description: Expert code reviewer. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.

Bad example:

description: Helps with code

Tip: Include "PROACTIVELY" or "Use immediately" for automatic delegation.

Step 4: Configure Tools

Grant only necessary tools for security and focus.

Read-only (reviewers, analyzers):

tools: Read, Grep, Glob, Bash

Editors (fixers, debuggers):

tools: Read, Edit, Bash, Grep, Glob

Creators (generators):

tools: Write, Read, Bash

Omit to inherit all tools from main conversation.

Step 5: Write the System Prompt

Use workflow-based or checklist-based patterns from design-patterns.md.

Workflow pattern:

When invoked:
1. [Action 1]
2. [Action 2]
3. [Action 3]

Checklist pattern:

Review checklist:
- [ ] Item 1
- [ ] Item 2

Usage

Automatic Delegation

Claude automatically invokes subagents when description matches:

User: Review my recent code changes
Claude: [Invokes code-reviewer subagent automatically]

Explicit Invocation

Request a specific subagent:

User: Use the test-runner subagent to run all tests

Background Execution

Run subagents in background for parallel work:

User: Run tests in the background while I continue coding

Advanced Features

Background Execution

The Task tool supports run_in_background: true for parallel work:

Task(
  subagent_type: "test-runner",
  prompt: "Run full test suite",
  run_in_background: true
)
// Continue working
// Retrieve results with TaskOutput later

Resumable Agents

Long-running tasks can be resumed with full context:

# Initial invocation returns agentId
User: Analyze the auth module

# Later, resume with context preserved
User: Resume agent abc123 and analyze authorization too

Quick Reference

Minimal template:

---
name: my-agent
description: Specific trigger conditions and use cases
---

You are [role].

When invoked:
1. [Step 1]
2. [Step 2]

Create project subagent: .claude/agents/my-agent.md Create user subagent: ~/.claude/agents/my-agent.md

See templates: example-templates.md See patterns: design-patterns.md