Skill: xiejinsong/create-team (version 1.0.0)

--- name: create-team description: Builds a runnable Claude Code Agent Teams skill package — produces SKILL.md as a lead-operator playbook, agents/<role>.md subagent definitions for runtime spawning, references/<role>.md role specs with 8 sections (Scope/Inputs/Outputs/Boundaries + Spawn Prompt/Owned Paths/Task Template/Plan Approval), and optional hooks/. Use when the user wants a reusable multi-agent team that the team lead can spawn end-to-end, not just static role documentation. metadata: version: "2.0" language: en --- # Create A Runnable Agent Team Skill ## When To Use Use this skill when the user needs a **runnable** team package that a Claude Code team lead can execute end-to-end: - Spawn teammates via `Agent({subagent_type, team_name, name, prompt})` with prompts already templated - Seed tasks with `blockedBy` dependencies pre-mapped - Trust that file ownership across roles is conflict-free - Tear down the team cleanly when done If the user only needs pretty role docs (no intent to actually run a team), this skill is overkill — write plain markdown instead. ## Alignment With Agent Teams Runtime Read [`../agent-teams.md`](../agent-teams.md) (or the live page at `code.claude.com`) for the runtime model. Key points this skill encodes: - **Subagent definitions are reusable** — teammates can be spawned with `subagent_type: <role>` if a definition exists at `.claude/agents/<role>.md` (project) or `~/.claude/agents/<role>.md` (user). The definition's `tools` allowlist and `model` are honored at runtime. - **3–5 teammates, 5–6 tasks each** — the documented sweet spot. - **Avoid file conflicts** — two teammates editing the same file overwrite each other; design Owned Paths so they don't overlap. - **Lead is fixed for team lifetime** — the SKILL.md plays the role of operating manual for that single lead. - **Teardown order matters** — shut down each teammate before `TeamDelete`, or you'll leak resources. ## Output Structure ```text <skill-root>/ # same as `name`, lowercase-hyphen ├── SKILL.md # lead's operating playbook ├── agents/ # source of truth for subagent definitions │ ├── <role-a>.md # frontmatter: name/description/tools/model │ └── <role-b>.md ├── references/ │ ├── member.md # role index + suggested invocation order │ ├── <role-a>.md # 8-section role spec │ └── <role-b>.md └── hooks/ # optional quality gates ├── teammate-idle.sh └── task-completed.sh ``` `agents/*.md` are **source files**. To make them runtime-discoverable, the lead either copies or symlinks them into `.claude/agents/` (project scope) or `~/.claude/agents/` (user scope) — see Bootstrap step in the generated SKILL.md. ## Workflow ### 1. Preflight (clarify with user) Confirm before writing anything: - **Team domain and closed loop** — what end-to-end outcome the team owns. - **Skill root and `name`** — must match exactly; lowercase-hyphen (e.g. `code-review-team`). - **Role count and slugs** — target **3–5 roles**; if the user wants 1–2 roles, recommend subagents instead; if >6, propose merging. - **Roles can run truly in parallel?** — if they all need the same files, this should be sequential, not a team. - **Runtime preconditions** — note in SKILL.md that the lead must verify Claude Code ≥2.1.32 and [REDACTED_SECRET]. ### 2. Define each role (8 sections, not 4) For every role, fill all 8 sections (full skeleton in [references/templates.md](references/templates.md)): | # | Section | Purpose | |---|---------|---------| | 1 | Scope | What the role delivers | | 2 | Inputs | What it needs from user/peers | | 3 | Outputs | Artifacts produced | | 4 | Boundaries | Explicit non-goals | | 5 | **Spawn Prompt** | Verbatim text the lead pastes into `Agent({prompt})` | | 6 | **Owned Paths** | File globs this role exclusively writes (cross-role overlap forbidden) | | 7 | **Task Template** | 3–6 typical tasks with `blockedBy` edges | | 8 | **Plan Approval** | `true` for risky/architectural roles, else `false` | ### 3. Generate dual-track artifacts per role - `agents/<slug>.md` — subagent definition. Frontmatter: `name`, `description`, `tools` allowlist, `model`. Body = role's operating instructions (this is appended to the teammate's system prompt at spawn). - `references/<slug>.md` — full 8-section spec. This is for humans and for the lead to reference; **not** loaded into teammate context automatically. Keep them in sync — drift between `agents/` and `references/` is the #1 failure mode. ### 4. Write SKILL.md as a lead playbook Required sections (skeleton in [references/templates.md](references/templates.md)): 1. **Preflight** — env var check, version check, `teammateMode` choice 2. **Install agents** — copy/symlink `agents/*.md` to `.claude/agents/` so `subagent_type` works 3. **Bootstrap** — concrete `TeamCreate` + per-role `Agent` calls with the spawn prompts wired up 4. **Task seeding** — `TaskCreate` calls with `addBlockedBy` mapped from each role's Task Template 5. **Steady state** — when to `SendMessage`, how to handle `plan_approval_request`, when to wait 6. **Teardown** — per-teammate `shutdown_request` loop, then `TeamDelete` 7. **Known Limits** — fixed lead, no `/resume` of in-process teammates, permissions set at spawn ### 5. (Optional) Add hooks/ For quality gates — see `references/templates.md` "Hooks" section. Wire them via project `.claude/settings.json`. Examples: - `TeammateIdle` exit code 2 → block idle until tests pass - `TaskCompleted` exit code 2 → block completion if acceptance artifact missing ### 6. Self-check Run [references/checklist.md](references/checklist.md). The hardest constraint: **Owned Paths must have zero cross-role overlap**. ## Key Design Rules 1. **Dual-track or nothing** — every role gets both `agents/<slug>.md` and `references/<slug>.md`. One without the other is a half-built team. 2. **No file conflicts at design time** — overlapping Owned Paths = guaranteed runtime overwrite. Refactor roles until disjoint. 3. **Spawn prompts are self-contained** — a teammate doesn't read the references/ folder unless told to. The Spawn Prompt must include all task-specific context the teammate needs. 4. **Sized for runtime** — 3–5 roles, 5–6 tasks per role. More = coordination overhead eats the gains (see agent-teams.md). 5. **Teardown is part of the spec** — every team SKILL.md ends with a shutdown sequence. Skipping this leaks tmux sessions and team configs. ## References - Skeletons (SKILL.md / agents/ / references/<role>.md / hooks): [references/templates.md](references/templates.md) - Validation checklist (run before declaring done): [references/checklist.md](references/checklist.md) - Worked example: `../code-review-team/` — a 3-person parallel PR review team ## Common Edge Cases - **1–2 roles** — recommend [subagents](https://code.claude.com/docs/en/sub-agents) instead. Agent Teams overhead doesn't pay off below 3. - **>6 roles** — merge until ≤5; coordination overhead grows superlinearly. - **Roles share files** — split the file or merge the roles. Don't ship overlapping Owned Paths. - **One role is the bottleneck** — split its Task Template into more granular tasks (5–6/role rule), or split into two roles with a clean handoff. - **User has existing role docs** — normalize slugs/file names first, then backfill the 4 new sections (Spawn Prompt / Owned Paths / Task Template / Plan Approval) and generate `agents/`.

path: references/templates.md
content: # Templates

Replace `{PLACEHOLDERS}` as needed. Naming: `{SKILL_NAME}` and all `{ROLE_SLUG}` values must be `a-z 0-9 -`, no leading/trailing `-`, no `--`.

Placeholder keys:
- `{SKILL_ROOT}` — folder name, equal to `{SKILL_NAME}`
- `{SKILL_NAME}` — YAML `name`, must equal folder
- `{TEAM_TITLE}` — display title (e.g. "Code Review Team")
- `{DESCRIPTION}` — capability + trigger, ≤1024 chars
- `{ROLE_NAME}`, `{ROLE_SLUG}` — per role
- `{TOOLS_ALLOWLIST}` — comma-separated tool names (Read, Grep, Glob, Bash, Edit, Write, ...)
- `{MODEL}` — `opus` | `sonnet` | `haiku` | omit to inherit lead

---

## 1. `SKILL.md` skeleton (lead playbook)

```markdown
---
name: {SKILL_NAME}
description: {DESCRIPTION}
metadata:
  version: "1.0"
---

# {TEAM_TITLE}

## Team Positioning

(One sentence: what closed loop this team owns. List members. List covered phases.)

## Collaboration Principles

1. ... (e.g. file ownership is enforced via Owned Paths — never edit another role's files)
2. ... (e.g. cross-role conflicts escalate to lead via `SendMessage`)
3. ... (e.g. all artifacts land in `outputs/` with role-prefixed filenames)

## Preflight (lead runs once)

- Verify Claude Code version: `claude --version` ≥ 2.1.32
- Verify env: `echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` returns `1`
- Choose `teammateMode` in `~/.claude/settings.json` (`in-process` or `tmux`)

## Install Agents (one-time per project or user)

Copy or symlink subagent definitions so `subagent_type` resolves:

\```bash
# project scope
mkdir -p .claude/agents
cp {SKILL_ROOT}/agents/*.md .claude/agents/

# OR user scope (reusable across projects)
mkdir -p ~/.claude/agents
ln -sf "$PWD/{SKILL_ROOT}/agents/"*.md ~/.claude/agents/
\```

## Bootstrap

\```
TeamCreate({team_name: "{SKILL_NAME}", description: "..."})

Agent({
  team_name: "{SKILL_NAME}",
  name: "{ROLE_SLUG_A}",
  subagent_type: "{ROLE_SLUG_A}",
  prompt: "<paste from references/{ROLE_SLUG_A}.md §Spawn Prompt, with placeholders filled>"
})

Agent({
  team_name: "{SKILL_NAME}",
  name: "{ROLE_SLUG_B}",
  subagent_type: "{ROLE_SLUG_B}",
  prompt: "<paste from references/{ROLE_SLUG_B}.md §Spawn Prompt>"
})
\```

## Task Seeding

For each role, instantiate its Task Template:

\```
TaskCreate({subject: "...", description: "..."})  // returns id=1
TaskCreate({subject: "...", description: "..."})  // returns id=2
TaskUpdate({taskId: "2", addBlockedBy: ["1"], owner: "{ROLE_SLUG_B}"})
\```

## Steady State

- Teammate idle → check task list; assign next task or send instruction
- `plan_approval_request` from teammate → review against role's Plan Approval criteria; approve or reject with feedback
- Cross-role conflict → lead arbitrates via `SendMessage` (do not let teammates negotiate edits to disputed files)

## Teardown

\```
# 1. Shut each teammate down (wait for ack before next)
SendMessage({to: "{ROLE_SLUG_A}", message: {type: "shutdown_request"}})
SendMessage({to: "{ROLE_SLUG_B}", message: {type: "shutdown_request"}})

# 2. Only after all teammates are gone:
TeamDelete()
\```

## Known Limits

- No `/resume` for in-process teammates — restart spawns new ones
- Lead is fixed for team lifetime; cannot promote a teammate
- Permissions set at spawn time; per-teammate mode changes only after spawn
- Task status can lag — verify state before re-assigning
- One team per lead; clean up before creating another

## Members And References

- Member index: [references/member.md](references/member.md)
- Role specs (read on demand):
  - [references/{ROLE_SLUG_A}.md](references/{ROLE_SLUG_A}.md)
  - [references/{ROLE_SLUG_B}.md](references/{ROLE_SLUG_B}.md)
```

---

## 2. `agents/{ROLE_SLUG}.md` skeleton (subagent definition)

This is the **runtime** file. Body is appended to the spawned teammate's system prompt.

```markdown
---
name: {ROLE_SLUG}
description: {one-line role purpose; used by lead to pick subagent_type}
tools: {TOOLS_ALLOWLIST}
model: {MODEL}
---

You are the {ROLE_NAME} on the {TEAM_TITLE}.

## Your Responsibility

(2–4 lines, lifted from references/{ROLE_SLUG}.md §Scope.)

## Files You Own

You may edit only files matching:
- `path/glob/one/**`
- `path/glob/two/*.ext`

Never edit files outside this list. If you need a change there, message the owning teammate or escalate to the lead.

## Operating Rules

1. (e.g. always run `<test command>` before marking a task completed)
2. (e.g. write outputs to `outputs/{ROLE_SLUG}-<date>.md`)
3. (e.g. if blocked >5 minutes, message the lead with what's blocking)

## Plan Approval

{If true:} Before any code changes, submit a plan and wait for lead approval.
{If false:} Proceed directly to implementation; no plan approval needed.
```

**Notes**:
- `tools` is enforced — omitting a tool means the teammate can't call it. `SendMessage` and task tools are always available regardless.
- `model` overrides the lead's default; omit to inherit.
- The spawn `prompt` (passed via `Agent({prompt})`) is **separate** from this body. The prompt carries the specific task; this body carries the role's standing rules.

---

## 3. `references/{ROLE_SLUG}.md` skeleton (8-section role spec)

```markdown
# {ROLE_NAME} (`{ROLE_SLUG}`)

## 1. Scope

- Deliverable-level capability bullets.

## 2. Inputs

- What this role needs from users / other roles.

## 3. Outputs

- Artifacts produced; acceptance-facing deliverables.

## 4. Boundaries

- Explicit non-goals. What this role does NOT do.

## 5. Spawn Prompt

Lead pastes this verbatim into `Agent({prompt})`. Replace `{{PLACEHOLDERS}}` with task specifics.

\```text
You are the {ROLE_NAME} on the {TEAM_TITLE}.

Task: {{TASK_DESCRIPTION}}

Context:
- {{REPO_PATH_OR_PR}}
- {{CONSTRAINTS}}

Acceptance:
- {{HOW_LEAD_WILL_VERIFY}}

Coordinate via the shared task list. When you finish a task, call TaskUpdate to mark it completed and pick up the next available task. If you hit a blocker, message the lead.
\```

## 6. Owned Paths

This role exclusively writes:

- `path/glob/one/**`
- `path/glob/two/*.ext`

Cross-role overlap is forbidden — see SKILL.md collaboration principles.

## 7. Task Template

Typical tasks (3–6) the lead seeds at bootstrap. `blockedBy` lists peer slugs whose task must complete first.

| Task | Description | blockedBy |
|------|-------------|-----------|
| {ROLE_SLUG}-1 | ... | — |
| {ROLE_SLUG}-2 | ... | {ROLE_SLUG}-1 |
| {ROLE_SLUG}-3 | ... | {OTHER_ROLE_SLUG}-2 |

## 8. Plan Approval

- **Required**: `true` | `false`
- **If true, criteria the lead applies when reviewing**: ...
```

---

## 4. `references/member.md` skeleton

```markdown
# {TEAM_TITLE} — Member Index

This team has **N** Agents and covers the lifecycle: **{phases}**. All members are Claude Code teammates (no human-in-the-loop required by default).

| Role | Slug | Responsibility | Spec | Definition |
|------|------|----------------|------|------------|
| {ROLE_NAME_A} | `{ROLE_SLUG_A}` | ... | [{ROLE_SLUG_A}.md]({ROLE_SLUG_A}.md) | [../agents/{ROLE_SLUG_A}.md](../agents/{ROLE_SLUG_A}.md) |

## Suggested Invocation Order

- **First-time setup**: ...
- **Per-iteration**: ...

## Cross-Role Conflict Rule

If two roles' work conflicts (e.g. ownership boundary disputes, contradictory acceptance criteria), the **lead** arbitrates. Teammates do not negotiate edits to disputed files directly.
```

---

## 5. Hooks (optional)

Wire in project `.claude/settings.json`:

```json
{
  "hooks": {
    "TeammateIdle": [{"command": "{SKILL_ROOT}/hooks/teammate-idle.sh"}],
    "TaskCompleted": [{"command": "{SKILL_ROOT}/hooks/task-completed.sh"}]
  }
}
```

### `hooks/teammate-idle.sh` (block idle until tests pass)

```bash
#!/usr/bin/env bash
# Exit 2 sends feedback to teammate and keeps them working.
set -e
if ! npm test --silent; then
  echo "Tests failing — fix before going idle." >&2
  exit 2
fi
exit 0
```

### `hooks/task-completed.sh` (block completion if artifact missing)

```bash
#!/usr/bin/env bash
# Read the task ID from stdin (provided by hook context).
task_id="$1"
artifact_dir="outputs/"
if ! ls "$artifact_dir" | grep -q "task-${task_id}-"; then
  echo "Task ${task_id} marked complete but no artifact at ${artifact_dir}/task-${task_id}-*" >&2
  exit 2
fi
exit 0
```

Adapt to the team's actual quality bar. Hooks are **per-project** (project `.claude/settings.json`), so each install of the team can tune them.


path: references/checklist.md
content: # Virtual Team Skill Checklist

Run before declaring the team skill done. **Critical** items will break the team at runtime; **Recommended** items hurt usability or maintainability.

## Frontmatter And Discoverability (Critical)

- [ ] `name`: `a-z 0-9 -` only; no leading/trailing `-`; no `--`; ≤64 chars; **exactly matches skill root folder name**
- [ ] `description`: includes both **capability summary** and **trigger scenario**; ≤1024 chars; third-person
- [ ] `metadata.version` present (helps track skill evolution)

## Structure (Critical)

- [ ] `SKILL.md` exists at skill root
- [ ] `agents/<slug>.md` exists for **every** role declared in `references/member.md`
- [ ] `references/member.md` exists and lists **every** role with links to both spec and definition
- [ ] `references/<slug>.md` exists for every role; links from `member.md` resolve
- [ ] No role appears in `agents/` without a matching `references/`, or vice versa (dual-track invariant)

## Subagent Definitions — `agents/<slug>.md` (Critical)

For each role:

- [ ] Frontmatter contains `name`, `description`, `tools`, `model` (model may be omitted to inherit lead)
- [ ] `name` in frontmatter equals filename slug
- [ ] `tools` allowlist includes everything the role's Spawn Prompt asks the teammate to do (e.g. don't ask the role to "edit files" without `Edit` and `Write` in tools)
- [ ] Body explicitly lists **Files You Own** matching the role's Owned Paths in `references/<slug>.md`

## Role Specs — `references/<slug>.md` (Critical)

For each role, all 8 sections present:

- [ ] 1. Scope
- [ ] 2. Inputs
- [ ] 3. Outputs
- [ ] 4. Boundaries
- [ ] 5. **Spawn Prompt** — verbatim text the lead can paste; ≥3 lines of task-specific context (not just "do X"); contains placeholder slots for the lead to fill
- [ ] 6. **Owned Paths** — explicit globs, not vague descriptions
- [ ] 7. **Task Template** — 3–6 tasks with `blockedBy` edges
- [ ] 8. **Plan Approval** — boolean, with criteria if `true`

## Cross-Role Invariants (Critical — runtime correctness)

- [ ] **Owned Paths have zero cross-role overlap.** Walk every pair of roles; if two glob lists could match the same file, refactor. This is the #1 source of teammate edit collisions.
- [ ] Task Template `blockedBy` references resolve to existing tasks in other roles' templates (no dangling deps)
- [ ] Total team size is **3–5 roles**. If <3, recommend subagents instead. If >5, merge until ≤5.
- [ ] Per-role task count is **3–6**. Beyond that, coordination overhead grows; below it, the role is too small.

## SKILL.md Playbook Sections (Critical)

The SKILL.md must contain operating sections for the lead, not just team description:

- [ ] **Preflight** — Claude Code version, env var, `teammateMode` checks
- [ ] **Install Agents** — copy/symlink instructions for `.claude/agents/`
- [ ] **Bootstrap** — concrete `TeamCreate` + per-role `Agent` calls
- [ ] **Task Seeding** — `TaskCreate` examples wiring up `blockedBy`
- [ ] **Steady State** — when to message, how to handle plan approval requests
- [ ] **Teardown** — per-teammate `shutdown_request` loop, then `TeamDelete`
- [ ] **Known Limits** — at minimum: fixed lead, no `/resume`, permissions set at spawn

## Content Quality (Recommended)

- [ ] `SKILL.md` ideally <500 lines; long tables/details moved to `references/`
- [ ] Terminology is consistent across SKILL.md / agents/ / references/ (same role uses one slug everywhere)
- [ ] Collaboration principles are actionable (e.g. "outputs land in `outputs/<slug>-*.md`"), not aspirational
- [ ] Cross-role conflict resolution rule stated once in SKILL.md or `member.md`

## Hooks (If Provided)

- [ ] Each hook script is executable (`chmod +x`)
- [ ] Each hook uses exit code 2 for "block + send feedback" (per Claude Code hook spec)
- [ ] SKILL.md documents the `.claude/settings.json` snippet to wire them up
- [ ] Hooks are scoped per-team (won't fire for unrelated work in the same project)

## Documentation Links

- [ ] All `[link](path)` references resolve (no broken paths after rename/move)
- [ ] Reference depth ≤1 from `SKILL.md` (no chains like SKILL.md → ref → ref)

## Final Smoke Test (Recommended)

Before shipping, dry-run the SKILL.md with a stub task:

- [ ] Preflight commands run cleanly
- [ ] `cp agents/*.md ~/.claude/agents/` (or symlink) succeeds and files appear
- [ ] `TeamCreate` + first `Agent` spawn returns without error
- [ ] First teammate's spawn prompt produces sensible output for a trivial input
- [ ] Teardown leaves no orphaned tmux sessions (`tmux ls` if applicable)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)