Sub-Agents Cheatsheet

Configuration Format (.claude.exs)

%{
  subagents: [
    %{
      name: "agent-name",           # Required: kebab-case
      description: "MUST BE USED...", # Required: delegation trigger
      prompt: "You are...",          # Required: system prompt
      tools: [:read, :write],        # Optional: defaults to all
      usage_rules: [:package]        # Optional: best practices
    }
  ]
}

Field Reference

Creation Methods

# Method 1: Meta Agent (Recommended)
# Just ask Claude: "Create a sub-agent for GraphQL"

# Method 2: Interactive Generator
mix claude.gen.subagent

# Method 3: Manual
# Edit .claude.exs then run:
mix claude.install

Tool Inheritance

Usage Rules Format

# Package root rules
:package_name              # deps/package_name/usage-rules.md

# All package rules  
"package_name:all"         # deps/package_name/usage-rules/*

# Specific sub-rule
"package_name:subrule"     # deps/package_name/usage-rules/subrule.md

# Special cases
:usage_rules_elixir        # Elixir best practices
:usage_rules_otp           # OTP patterns

Design Principles

# ❌ Bad: Assumes context
prompt: "Continue from where we left off..."

# ✅ Good: Self-contained
prompt: """
## Context Discovery
1. Check priv/repo/migrations/
2. Read latest migration
3. Check lib/*/repo.ex
"""

Performance Tips

1. Specify files: "Check lib/app/schema.ex first"
2. Use patterns: grep "defmodule.*Schema" not read **/*
3. Limit reads: Don't read entire directories
4. Clean slate: Each invocation starts fresh

Common Patterns

# Database Expert
%{
  name: "database-expert",
  description: "MUST BE USED for migrations and schema",
  tools: [:read, :write, :grep, :bash],
  prompt: """
  ## Check First
  - priv/repo/migrations/
  - lib/*/schemas/
  """
}

# Test Specialist
%{
  name: "test-expert",
  description: "MUST BE USED for ExUnit tests",
  tools: [:read, :write, :edit, :bash],
  usage_rules: [:usage_rules_elixir]
}

# Phoenix Expert
%{
  name: "phoenix-expert",
  description: "MUST BE USED for controllers and views",
  tools: [:read, :edit, :grep],
  usage_rules: [:phoenix]  # If Phoenix 1.8+
}

Troubleshooting