claude-agent-teams-skill

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

• Kickoff Templates (6 scenarios) -- code review, research, refactoring, migration, documentation, testing
• Task-List Patterns (4 patterns) -- linear chain, fan-out/fan-in, pipeline, diamond dependency
• Role Cards (10 roles) -- architect, writer, auditor, researcher, tester, and more
• 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