Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
gutomec avatar

Squads

gutomec/ai-public-arsenal

  • 129 installs
  • 9 repo stars
  • Updated April 24, 2026
  • gutomec/ai-public-arsenal

Create, validate, run, and manage portable multi-agent squads with workflows that run across Claude Code, Codex, Gemini CLI, Cursor, and other runtimes.

About

A runtime-agnostic orchestrator for building and running multi-agent squads following the Squad Protocol, with adapters for multiple agent runtimes. A developer uses it when creating, validating, running, or migrating portable AI agent teams and workflows.

  • Runtime-neutral squads with per-runtime adapters
  • Bounded iteration and fail-closed permission defaults

Squads by the numbers

  • 129 all-time installs (skills.sh)
  • Ranked #3,702 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
  • Data as of Jul 24, 2026 (Skillselion catalog sync)
npx skills add https://github.com/gutomec/ai-public-arsenal --skill squads

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs129
repo stars★ 9
Last updatedApril 24, 2026
Repositorygutomec/ai-public-arsenal ↗

What it does

Create, validate, run, and manage portable multi-agent squads with workflows that run across Claude Code, Codex, Gemini CLI, Cursor, and other runtimes.

Files

SKILL.mdMarkdownGitHub ↗

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.

IntentKeywordsLoad references
DISCOVERlist, show, find, search, inspect, info, describereferences/01-discovery.md
CREATEcreate, new, scaffold, generate, build squadreferences/02-creation.md, references/05-schemas.md
VALIDATEvalidate, check, verify, fix, repair, lint, auditreferences/03-validation.md
ACTIVATEactivate, register, install, deps, enablereferences/04-activation.md
MODIFYadd agent, remove, update, add task, add workflowreferences/05-schemas.md
EXECUTErun, execute, start, launch, resume, retryreferences/06-workflows.md, references/07-execution.md
ADAPTadapter, runtime, compatibility, feature matrixreferences/08-runtime-contract.md, references/11-adapters-guide.md
UPGRADEupgrade, migrate, convert, v4references/09-upgrade.md
OBSERVEstate, status, traces, artifacts, flow, runsreferences/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)

---
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

Related skills

mattpocockSetup Matt Pocock SkillsScaffold the per-repo configuration that Matt Pocock’s engineering agent skills rely on so they understand the issue tracker, triage labels, and domain documentation la495k196kopen.feishu.cnLark AppsConnect Claude, Cursor or custom agents directly to Lark (Feishu) for messaging, document automation, approval workflows and enterprise data access.402kjuliusbrusseeCavemanSlash token usage by roughly 75% while keeping every technical detail intact when working with Claude Code, Cursor or similar agents.391k94.7klarksuiteLark Skill MakerQuickly turn any Lark/Feishu OpenAPI call or multi-step workflow into a reusable agent skill with its own SKILL.md.386k16kxixu-meRunning Claude Code Via Litellm CopilotRun Claude Code at a fraction of the cost by routing requests through LiteLLM to the GitHub Copilot Chat API.270k72runcomfy-comCodex PetGenerate a complete Codex Pet spritesheet and metadata from one reference image without needing an OpenAI key or Codex Pro.246k10
AI & Agent Buildingagentsautomation
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.