team-orchestrator

team-orchestrator

A Claude Code skill that acts as a team architect — analyzes your task, decides whether an Agent Team is needed, designs the optimal team structure with clear file ownership, and generates ready-to-use team prompts.

What it does

Claude Code Agent Teams let you spawn multiple Claude sessions to work in parallel. But three questions remain:

1. Should I use a team? Many tasks don't need one — a subagent or single agent is cheaper and faster.
2. How should I split the work? Bad role definitions and overlapping file ownership cause merge conflicts.
3. What prompt do I write? Crafting a good team prompt from scratch every time is tedious.

This skill answers all three automatically.

How it works

When you describe a task, the skill runs a 5-step analysis:

Task Description
      |
      v
1. Task Analysis      -- parallelism, coupling, scale, dependencies
      |
      v
2. Team Decision      -- Team / Subagent / Single Agent / Phased
      |
      v
3. Quality Calibration -- model selection preference
      |
      v
4. Team Design        -- roles, file ownership, communication rules
      |
      v
5. Prompt Generation  -- structured team prompt ready to execute

It will also actively discourage using a team when the task doesn't warrant it (single-file fixes, highly coupled code, linear dependencies).

Install

Option 1: Plugin marketplace (recommended)

/plugin marketplace add choiszt/team-orchestrator
/plugin install team-orchestrator@team-orchestrator-marketplace

Option 2: Copy to personal skills

git clone https://github.com/choiszt/team-orchestrator.git
cp -r team-orchestrator/skills/team-orchestrator ~/.claude/skills/team-orchestrator

Option 3: Local plugin (for development)

claude --plugin-dir ./team-orchestrator

Usage

Explicit — invoke directly:

/team-orchestrator Refactor the auth system across backend, frontend, and tests

Automatic — just describe your task naturally. The skill activates when it detects keywords like "team", "parallel", "swarm", or when the task characteristics suggest parallel execution.

Examples

Recommends a team

> Add structured logging to user-service, order-service, and payment-service

Task Analysis:
- Parallelism: High (3 independent services)
- Coupling: Low (no shared files)
- Scale: ~12 files

Recommendation: Team (3 teammates, one per service)

Discourages a team

> Use a team to fix this CSS alignment bug

This is a single-file fix — no need for a team. Each teammate costs ~5x tokens.
I'll fix it directly.

Suggests a phased approach

> Use a team to migrate the entire project from JS to TypeScript

JS -> TS migration has high coupling across modules. Suggest:
- Phase 1 (single agent): tsconfig, shared types, build setup
- Phase 2 (team): parallel migration by module

Skill structure

skills/team-orchestrator/
├── SKILL.md                          # Core workflow and principles
├── references/
│   ├── decision-matrix.md            # Scoring system and case studies
│   ├── team-patterns.md              # 5 reusable team templates
│   ├── anti-patterns.md              # 8 common mistakes to avoid
│   └── cost-estimation.md            # Token cost and ROI guidelines
└── scripts/
    └── validate-team-config.py       # Validates no file ownership overlaps

Key principles

1. File ownership is the #1 rule — Two teammates editing the same file = guaranteed conflicts.
2. Lead writes no code — The lead coordinates, defines interfaces, and monitors progress.
3. Be willing to say no — Not every task needs a team.
4. Interfaces before implementation — Shared types and API contracts must exist before teammates start.
5. Start small — Begin with 2-3 teammates on non-code tasks before scaling up.
6. Transparent estimation — Always inform users of approximate token costs.

License

MIT