claude-agent-teams-skill

Agent teams orchestration skill for Claude Code. 5-level progressive disclosure, 4 playbooks, 130+ citations from official docs.

Quick Start

npx claude-agent-teams-skill init

Then open Claude Code and type /claude-agent-teams.

What You Get

| Content | Count | Description | |---------|-------|-------------| | Skill levels | 5 | L0 quickstart through L4 advanced patterns | | Playbooks | 4 | Kickoff templates, task patterns, role cards, troubleshooting | | Reference files | 2 | Agent teams mechanics, CLI and config reference | | Citations | 130+ | Links to 22 official documentation pages |

Installation

Project-local (recommended)

Installs to .claude/skills/ in your current project:

npx claude-agent-teams-skill init

Global

Installs to ~/.claude/skills/ so the skill is available in all projects:

npx claude-agent-teams-skill init --global

Overwrite existing

If you already have the skill installed and want to update:

npx claude-agent-teams-skill init --force

Usage Examples

Once installed, use /claude-agent-teams in Claude Code. Ask questions like:

• "Create a 3-person team to review PR #142" -- uses kickoff templates to scaffold the team
• "How do task dependencies work?" -- loads task-list patterns playbook
• "What role should a read-only reviewer use?" -- pulls from role cards
• "Teammates are not responding" -- routes to troubleshooting playbook

The skill uses a routing brain (SKILL.md) to match your question to the right content level and load only what is needed, keeping context usage minimal.

CLI Reference

claude-agent-teams-skill init [options]

| Flag | Short | Description | |------|-------|-------------| | --global | -g | Install to ~/.claude/skills/ (global) | | --force | -f | Overwrite existing installation | | --help | -h | Show help message | | --version | -v | Show version number |

Contents Overview

Skill Levels

• L0 -- Quick-start (first team in 60 seconds)
• L1 -- Core mechanics (TaskCreate, SendMessage, teammate spawning)
• L2 -- Intermediate patterns (plan mode, wave-based spawning, role cards)
• L3 -- Advanced workflows (dependency graphs, citation auditing, red-teaming)
• L4 -- Expert patterns (cost optimization, failure recovery, multi-wave orchestration)

Playbooks

1. Kickoff Templates (6 scenarios) -- code review, research, refactoring, migration, documentation, testing
2. Task-List Patterns (4 patterns) -- linear chain, fan-out/fan-in, pipeline, diamond dependency
3. Role Cards (10 roles) -- architect, writer, auditor, researcher, tester, and more
4. Troubleshooting (8 limitations + 5 guides) -- common issues, workarounds, open questions

Reference Files

• Agent Teams Mechanics -- 20-section deep reference covering TeamCreate, TaskCreate, SendMessage, spawning, idle states, plan mode, cost model
• CLI and Config Reference -- CLI flags, settings.json keys, environment variables, .claude/agents/ configuration

How It Works

The skill uses fork context loading: SKILL.md is always loaded (~28KB), but playbooks and reference files are loaded on-demand only when relevant to your query. This keeps the context footprint small while providing comprehensive coverage.

SKILL.md (always loaded)
  |
  +-- routes to --> playbooks/*.md (on-demand)
  +-- routes to --> reference/*.md (on-demand)
  +-- routes to --> sources/citations.md (on-demand)

Development

Run tests

npm test

Verify before publishing

node scripts/verify-skill.js

Publish

Create a GitHub Release -- the publish workflow handles npm publish automatically.

License

MIT