Create Worker

This skill provides comprehensive guidance for creating and configuring workers in Claude Code.

Understanding Workers

Workers are specialized AI assistants that Claude Code can delegate tasks to. Each worker:

Operates in its own context window (preserving main conversation context)
Has a specific purpose and expertise area
Can be configured with specific tools and permissions
Includes a custom system prompt guiding its behavior

When to Create Workers

Create a worker when:

Tasks require specialized expertise that benefits from focused instructions
Context preservation is important (workers don't pollute main context)
The same specialized workflow is needed repeatedly
Different tool permissions are needed for different tasks
Parallel execution of independent tasks is desired

Choose skills instead when:

The capability extends your knowledge without needing separate context
No specialized agent persona is needed
Tool restrictions are sufficient without full agent isolation

Choose slash commands when:

Users need explicit control over when to invoke functionality
The workflow should be user-initiated, not model-initiated

Two Approaches to Workers

Approach 1: File-Based Agents

Persistent worker definitions stored as Markdown files.

Locations (in priority order):

Location Scope Priority

.claude/agents/

Current project Highest

~/.claude/agents/

All projects Lower

File Format:

name: agent-name description: Description of when this agent should be used tools: Read, Write, Bash, Glob, Grep # Optional - omit to inherit all model: sonnet # Optional - sonnet, opus, haiku, or inherit permissionMode: default # Optional - see permission modes below skills: skill1, skill2 # Optional - skills to auto-load

Your agent's system prompt goes here. This defines the agent's role, capabilities, approach, and constraints.

Include:

Role definition and expertise areas
Step-by-step workflow for common tasks
Constraints and rules to follow
Output format expectations
Examples of good behavior

Approach 2: Teams Delegation

Dynamic worker delegation using teams for on-demand agents.

teams(action: 'delegate', tasks: [{ text: '<the agent's instructions and task>', assignee: 'worker-name' }])

Workers are delegated with a task description and an assignee name. Multiple workers can be delegated in parallel by including multiple tasks in the array.

Configuration Reference

Required Fields

Field Description

name

Unique identifier (lowercase letters, numbers, hyphens only, max 64 chars)

description

When the agent should be used (include "PROACTIVELY" for auto-invocation)

Optional Fields

Field Options Description

tools

Comma-separated list Specific tools to allow. Omit to inherit all.

model

sonnet , opus , haiku , inherit

Model to use. Default: inherit from session.

permissionMode

See below How permissions are handled

skills

Comma-separated list Skills to auto-load when agent starts

Permission Modes

Mode Behavior

default

Normal permission prompting

acceptEdits

Auto-accept file edits

bypassPermissions

Skip all permission prompts

plan

Planning mode (research only)

ignore

Ignore this agent

Available Tools

File Operations: Read , Write , Edit , Glob , Grep

Execution: Bash , BashOutput

Web: WebFetch , WebSearch

Specialized: Task , NotebookEdit , TodoWrite , Skill

Creating a Worker

Step 1: Define the Purpose

Answer these questions:

What specialized task does this agent handle?
What expertise or personality should it have?
What tools does it need (or shouldn't have)?
Should it be invoked automatically or explicitly?

Step 2: Choose the Approach

Use file-based agents when:

The agent will be reused across sessions
Team sharing via version control is desired
Configuration should persist

Use teams delegation when:

One-off or dynamic worker dispatch is needed
Workers are spawned as part of a workflow
Parallel execution is required

Step 3: Write the System Prompt

Structure the agent's prompt with these sections:

<role> Define who this agent is and what it excels at. </role>

ALWAYS do X
NEVER do Y </hard-rules> <preferences>
Prefer A over B
Prefer C over D </preferences> </constraints>

How to Approach Tasks

Phase 1: Description
Phase 2: Description
Phase 3: Description </workflow>

<examples> Good patterns and anti-patterns. </examples>

Step 4: Configure Tools and Permissions

Restrictive (read-only analysis):

tools: Read, Glob, Grep

Standard development:

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

Full access (omit tools field):

tools field omitted - inherits all tools

Step 5: Test and Iterate

Invoke the agent with a representative task
Observe where it struggles or deviates
Update the system prompt with clarifications
Add examples of correct behavior
Repeat until reliable

Agent Templates

Code Reviewer Agent

name: code-reviewer description: Expert code review specialist. Use PROACTIVELY after any code changes. Reviews for quality, security, and maintainability. tools: Read, Glob, Grep, Bash model: inherit

<role> You are a senior code reviewer ensuring high standards of code quality and security. </role>

Review Process

Gather Context: Run git diff, understand the changes
Analyze Each File: Check for issues systematically
Prioritize Findings: Critical > High > Medium > Low
Provide Actionable Feedback: Specific fixes, not vague suggestions

Review Checklist

<output-format> Organize feedback by priority:

Critical: Must fix before merge
High: Should fix
Medium: Consider improving
Low: Nice to have </output-format>

Debugger Agent

name: debugger description: Debugging specialist for errors and unexpected behavior. Use PROACTIVELY when encountering failures, test errors, or bugs. tools: Read, Edit, Bash, Glob, Grep

<role> You are an expert debugger specializing in root cause analysis. </role>

Debugging Protocol

Capture: Get error message, stack trace, reproduction steps
Hypothesize: Form theories about root cause
Investigate: Add logging, trace execution, check state
Isolate: Find the exact failure point
Fix: Apply minimal, targeted fix
Verify: Confirm fix works, no regressions

Three-Strike Rule

Strike 1: Targeted fix based on evidence
Strike 2: Step back, reassess assumptions
Strike 3: STOP - question the approach entirely </workflow>

NEVER fix symptoms without understanding root cause
ALWAYS reproduce before fixing
ALWAYS verify fix works </constraints>

Research Agent

name: researcher description: Deep research agent for complex questions requiring multi-source investigation. Use for architectural analysis, refactoring plans, or documentation questions. tools: Read, Glob, Grep, WebSearch, WebFetch model: opus

<role> You are a research specialist who finds comprehensive answers through thorough investigation. </role>

Research Process

Phase 1: Plan Investigation

Identify what needs to be researched
Map out search strategies
List relevant code areas

Phase 2: Deep Exploration

Search codebase thoroughly
Read relevant files completely
Use web search for external docs
Trace dependencies

Phase 3: Synthesize

Cross-reference findings
Identify patterns and gaps
Form coherent understanding

Phase 4: Report

Direct answer with evidence
File paths and line numbers
Confidence level and caveats
Recommended next steps </workflow>

Go deep, not shallow
Cite specific evidence
Connect dots across sources
Acknowledge uncertainty </principles>

Parallel Worker Patterns

Pattern: Parallel Execution

Delegate multiple workers simultaneously for independent tasks:

teams(action: 'delegate', tasks: [ {text: 'Task 1: Review authentication module...', assignee: 'auth-reviewer'}, {text: 'Task 2: Review authorization module...', assignee: 'authz-reviewer'}, {text: 'Task 3: Review session handling...', assignee: 'session-reviewer'} ])

Pattern: Divergent Exploration (Delphi)

Delegate multiple workers with identical prompts for diverse perspectives:

teams(action: 'delegate', tasks: [ {text: 'Investigate why API latency increased...', assignee: 'oracle-1'}, {text: 'Investigate why API latency increased...', assignee: 'oracle-2'}, {text: 'Investigate why API latency increased...', assignee: 'oracle-3'} ])

Each worker explores independently, potentially discovering different clues.

Pattern: Synthesis After Parallel Work

After parallel workers complete:

teams(action: 'delegate', tasks: [{ text: 'Read all review tickets and synthesize findings...', assignee: 'synthesizer' }])

Best Practices

Prompt Engineering

Be specific about the role: Define expertise and personality clearly
Include constraints: Hard rules prevent unwanted behavior
Provide workflow: Step-by-step process guides execution
Add examples: Show good and bad patterns
Define output format: Structure expectations

Tool Selection

Principle of least privilege: Only grant needed tools
Read-only for analysis: Use Read, Glob, Grep for review agents
Full access rarely needed: Most agents don't need all tools
Bash is powerful but risky: Consider if really needed

Description Writing

For automatic invocation, include trigger phrases:

"Use PROACTIVELY when..."
"MUST BE USED for..."
"Automatically invoke for..."

For explicit invocation, be descriptive:

"Use when user asks to..."
"Invoke for..."

Common Anti-Patterns

Anti-Pattern Better Approach

Vague descriptions Specific trigger conditions

Overly long prompts Progressive disclosure via skills

All tools for every agent Minimal necessary tools

Generic "helper" agents Focused, specialized agents

No constraints Clear hard rules and preferences

CLI-Based Agents

Define agents dynamically via command line:

claude --agents '{ "quick-review": { "description": "Fast code review. Use proactively after changes.", "prompt": "You are a quick code reviewer. Focus on obvious issues only.", "tools": ["Read", "Grep", "Glob"], "model": "haiku" } }'

CLI agents have lower priority than file-based project agents but higher than user-level agents.

Integration with Skills

Agents can auto-load skills:

name: data-analyst description: Data analysis specialist skills: query-builder, visualization

The specified skills are loaded when the agent starts, giving it access to that specialized knowledge.

Troubleshooting

Agent Not Being Invoked

Check description includes clear trigger conditions
Add "PROACTIVELY" if automatic invocation is desired
Verify file is in correct location with correct frontmatter
Check for name conflicts with higher-priority agents

Agent Using Wrong Tools

Verify tools field syntax (comma-separated, no brackets)
Check tool names are exactly correct (case-sensitive)
If tools should inherit, omit the field entirely

Agent Behaving Incorrectly

Add more specific constraints
Include examples of correct behavior
Add "NEVER" rules for unwanted behaviors
Consider if the prompt is too long (move details to skills)

Quick Reference

Create project agent:

mkdir -p .claude/agents

Create .claude/agents/my-agent.md with frontmatter

Create user agent:

mkdir -p ~/.claude/agents

Create ~/.claude/agents/my-agent.md with frontmatter

Delegate via teams:

teams(action: 'delegate', tasks: [{text: '...', assignee: 'worker-name'}])

View/manage agents:

/agents

create-worker

Safety Notice

Copy this and send it to your AI assistant to learn