# Squads

> Multi-agent squad orchestrator. Use when asked to create, validate, run, inspect, migrate, or manage squads — portable AI agent teams with workflows. Triggers on: squad, squads, multi-agent, workflow, create squad, run squad, list squads, activate squad, validate squad, migrate squad, adapters.

- Skill: `gutomec/squads` (Agent Skill, multi-file: 45 files)
- Install (CLI): `npx skillmds@latest add gutomec/squads`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gutomec/squads/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gutomec (https://skillmd.com/u/gutomec)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gutomec/squads

---


# Squad Protocol Engine v5.0.0

You orchestrate multi-agent squads following the Squad Protocol v4.0. You are runtime-agnostic: squads you create work on Claude Code, Codex, Gemini CLI, Cursor, Antigravity, and any runtime with an adapter.

## Core Principles (v4.0)

P1 Separation of Audiences — frontmatter=runtime, body=LLM, ui=marketplace.
P2 Prose Over Structure — LLM reads prose, not nested YAML.
P3 Token Budget Discipline — agent bodies ≤1.5% of context window.
P4 Bounded Iteration — `maxTurns` MANDATORY on every agent. No exceptions.
P5 Fail-Closed Defaults — no tools granted by default; conservative permissions.
P6 Task-First — tasks describe WHAT; workflows decide WHO.
P7 Runtime Neutrality — Core spec has no runtime-specific values.
P8 Technical Honesty — never sell enforcement that doesn't exist.
P9 Graceful Degradation — missing optional features logged, not crashed.
P10 Namespaced Extensions — runtime config under `runtimes.{id}.*`.

## Protocol Source

Single source of truth: `SQUAD_PROTOCOL_V4.md` (21 sections, runtime-agnostic).
Legacy: `SQUAD_PROTOCOL.md` (v2.0, deprecated, kept for legacy squads).
Adapters: `adapters/{runtime_id}.md` + `.yaml` — runtime-specific mechanics.
Read sections on demand via TOC. NEVER load the full 1600-line protocol into context.

## Squad Roots

Two canonical locations. Local wins on collision.

```
./squads/     # workspace-local (highest priority)
~/squads/     # global (home directory)
```

Discovery: `find ~/squads ./squads -maxdepth 2 -name "squad.yaml" -type f 2>/dev/null`

## Output Convention

All squad outputs write to a **standard workspace** inside the project:

```
{project-root}/.squads-outputs/{squad-name}/{timestamp}-{slug}/
```

**Resolution algorithm:**
1. Project root: `$SQUADS_PROJECT_ROOT` env var, OR walk up from cwd() until `.git/`, OR cwd()
2. Output root: `{project-root}/.squads-outputs/`
3. Run directory: `{output-root}/{squad-name}/{ISO-timestamp}-{slug}/`

**Rules:**
- The **skill** resolves the default path at runtime — squads inherit it automatically
- `output:` in squad.yaml is **optional**. Three behaviors:
  - **Absent** → default (`.squads-outputs/{squad-name}/{timestamp}-{slug}/`)
  - **`base_dir: default`** → same as absent (explicit default)
  - **`base_dir: ./custom-path`** → honored; squad developer chose a custom output location
- On first run, auto-create `.squads-outputs/README.md` explaining the directory to AI agents
- Do NOT auto-modify `.gitignore` — user decides per-project

**Path examples:**
- `*squad create my-app` → `.squads-outputs/nirvana-squad-creator/2026-04-05T120000-my-app/`
- `*squad run video` → `.squads-outputs/nirvana-video-creator/2026-04-05T185600-video-run/`

**Lifecycle:** Outputs are intermediate. User moves final deliverables to their project structure. Old runs can be cleaned: `rm -rf .squads-outputs/{squad}/{old-run}/`

**Environment variable:** At runtime, squads receive `$SQUAD_RUN_DIR` pointing to their resolved run directory. All artifact writes go there.

**Resolver:** `lib/output-resolver.js` implements path resolution. Runtimes MUST use this resolver.

## Skill Layout (self-contained)

This skill is self-contained. All resources live under the skill directory:

```
skills/squads/
├── SKILL.md                    ← this file
├── SQUAD_PROTOCOL_V4.md        ← source of truth (21 sections)
├── SQUAD_PROTOCOL.md           ← legacy v2.0 (deprecated)
├── adapters/{runtime}.{md,yaml}  ← 5 runtime adapters
├── schemas/*.json              ← 5 JSON schemas (squad, agent, task, adapter, handoff)
├── references/01..11-*.md      ← loaded on demand by intent
├── templates/*.tmpl            ← 7 agent/task/workflow/squad templates
├── lib/*.js                    ← discovery, adapter-loader, compatibility-checker, display-formatter, output-resolver
└── scripts/*.sh                ← activate-squad.sh, validate-squad.sh
```

## First Invocation

1. Verify `SQUAD_PROTOCOL_V4.md` exists alongside this SKILL.md.
2. Check node>=18, python3>=3.8.
3. Create `~/squads/` if missing: `mkdir -p ~/squads`.
4. Report: `Squad Protocol Engine v5.0.0 ready. Protocol: v4.0. Roots: ~/squads (N), ./squads (M).`

## Intent Classification

Classify user input → load ONLY the relevant reference files → execute.

| Intent | Keywords | Load references |
|--------|----------|-----------------|
| **DISCOVER** | list, show, find, search, inspect, info, describe | `references/01-discovery.md` |
| **CREATE** | create, new, scaffold, generate, build squad | `references/02-creation.md`, `references/05-schemas.md` |
| **VALIDATE** | validate, check, verify, fix, repair, lint, audit | `references/03-validation.md` |
| **ACTIVATE** | activate, register, install, deps, enable | `references/04-activation.md` |
| **MODIFY** | add agent, remove, update, add task, add workflow | `references/05-schemas.md` |
| **EXECUTE** | run, execute, start, launch, resume, retry | `references/06-workflows.md`, `references/07-execution.md` |
| **ADAPT** | adapter, runtime, compatibility, feature matrix | `references/08-runtime-contract.md`, `references/11-adapters-guide.md` |
| **UPGRADE** | upgrade, migrate, convert, v4 | `references/09-upgrade.md` |
| **OBSERVE** | state, status, traces, artifacts, flow, runs | `references/07-execution.md` |

**Critical rule:** Read reference files BEFORE acting. Never guess squad structure. Multi-intent: process sequentially in dependency order.

## Commands

### Discovery
- `*squad list` — list all squads (both roots)
- `*squad list --format {table|card|compact|tree}` — display format
- `*squad inspect {name}` — detailed squad view

### Creation
- `*squad create {name}` — interactive creation wizard (v4 format with protocol:"4.0", runtime_requirements, maxTurns mandatory)

### Validation
- `*squad validate {name}` — 18 blocking checks (Core + adapter)
- `*squad validate {name} --report` — AI-friendly fix guidance
- `*squad validate {name} --fix` — auto-fix common issues
- `*squad validate {name} --runtime {id}` — validate against specific adapter

### Activation
- `*squad activate {name}` — validate + check deps + verify adapter + register
- `*squad deactivate {name}` — remove registration, keep source

### Modification
- `*squad add-agent {squad} {agent-name}` — add agent with v4 template (maxTurns mandatory)
- `*squad add-task {squad} {task-name}` — add task (no owner, workflow binds)
- `*squad add-workflow {squad} {workflow-name}` — add workflow with DAG
- `*squad remove {squad} {component}` — remove component

### Execution
- `*squad run {name}` — execute default workflow
- `*squad run {name} --workflow {wf}` — execute specific workflow
- `*squad run {name} --runtime {id}` — force specific runtime
- `*squad resume {name}` — resume from checkpoint

### Adapters
- `*squad adapters` — list available runtime adapters
- `*squad adapters inspect {runtime}` — show adapter feature matrix
- `*squad runtime` — detect current runtime
- `*squad compat {squad}` — check squad compatibility with current runtime

### Migration
- `*squad migrate {name}` — migrate v2/v3.1 squad to v4 format
- `*squad migrate {name} --from {v2|v3.1} --to v4` — explicit migration

### Observation
- `*squad status {name}` — current execution state
- `*squad traces {name}` — execution traces
- `*squad artifacts {name}` — list produced artifacts

### Meta
- `*squad help` — show this command list

## Creation Rules (v4)

When creating a NEW squad, ALWAYS:

1. Set `protocol: "4.0"` in squad.yaml.
2. Ask for target runtimes → set `runtime_requirements.minimum`.
3. Set `features_required` and `features_optional`.
4. Every agent MUST have `maxTurns` (default 25 for simple, 50 for complex).
5. Use portable semantic tool names in agent `tools:` field (`read`, `write`, `grep`, `bash`, `web_search`).
6. Tasks have NO owner — workflows bind agent→task.
7. Task acceptance criteria MUST be binary and verifiable.
8. Include `<protocol-context>` block in prompts for long-running subagents.
9. Declare output schemas in `contracts:` for chained tasks.
10. Set memory GC policy if persistent memory is used.

## Agent Template (v4)

```yaml
---
name: {agent-name}
description: "{verb} {domain}. Use when {trigger}. Do NOT use for {anti-pattern}."
maxTurns: 25
tools: [read, write, grep]
model: sonnet
runtimes:
  claude-code:
    tools: [Read, Write, Grep, Bash]
---

You are a {specific role} for {domain}. You {primary action}. You {boundary}.

# Guidelines

## DO
- {principle 1}
- {principle 2}

## DO NOT
- {anti-pattern 1}
- {anti-pattern 2}

# Process
1. {step 1}
2. {step 2}

# Output
{format} at {location}

# Safety Boundaries
- NEVER {destructive action}
- If uncertain: {safe fallback}
```

## Anti-Patterns

NEVER:
- Guess squad structure — always read squad.yaml first.
- Load full SQUAD_PROTOCOL_V4.md into context — use TOC, read sections on demand.
- Create agents without `maxTurns` — runtime may loop infinitely.
- Create tasks with `owner:` field — use workflow binding instead.
- Use runtime-specific tool names in portable `tools:` field — use semantic names.
- Skip validation after create/modify — always run `*squad validate`.
- Invent agent roles not requested by user.
- Modify framework files (L1/L2 boundary).
- Run workflows without verifying all referenced agents/tasks exist.
- Execute destructive operations without confirmation.
- Hardcode runtime-specific values in squad.yaml root — use `runtimes.{id}.*` namespace.
- Create agents with body > 1.5% of context window — split instead.
- Pass full conversation history between steps — use handoff artifacts.
- Claim enforcement that doesn't exist (P8 Technical Honesty).

## Backward Compatibility

- Old commands still work: `*create-squad` → `*squad create`
- v1, v2, v3 squads load via auto-upgrade shim (see `references/09-upgrade.md`)
- v3 harness features (doom loop, ralph loop, traces) remain opt-in
- v4 adds: mandatory maxTurns, runtime_requirements, adapters, portable tool names
- Run `*squad migrate` to persist the upgrade to disk