Repository navigation
Skill-based orchestration — decompose squad.agent.md into pluggable skills #255
Description
Summary
Decompose the monolithic squad.agent.md (1000+ lines) into a skill-based orchestration model where the coordinator dynamically loads capabilities from .squad/skills/ instead of inlining everything.
Origin: Discussion #169 by @swnger — https://github.com/bradygaster/squad/discussions/169
Why This Matters
- Context pressure: squad.agent.md is growing. Every new feature adds instructions the coordinator must hold in context, even when irrelevant to the current task.
- Modularity: Skills already exist at
.squad/skills/— this extends the pattern to coordinator capabilities themselves (init, migrations, state management, ceremonies). - SDK alignment: Skills become typed, testable modules in SDK mode (
defineSkill()in squad.config.ts). - Community extensibility: Third-party skills can be shared via marketplaces without modifying the core agent file.
Proposed Architecture
Current (monolithic)
squad.agent.md (1000+ lines)
├── Init Mode instructions
├── Team Mode instructions
├── Ceremony instructions
├── GitHub Issues Mode
├── PRD Mode
├── Ralph instructions
└── ... everything inline
Proposed (skill-based)
squad.agent.md (~200 lines — core orchestration only)
├── Identity, routing, model selection
├── Skill discovery and loading
└── Response mode selection
.squad/skills/
├── init-mode/SKILL.md — team creation flow
├── github-issues/SKILL.md — issue lifecycle
├── ceremonies/SKILL.md — ceremony execution
├── prd-intake/SKILL.md — PRD decomposition
├── ralph-monitor/SKILL.md — work queue management
├── casting/SKILL.md — name allocation
└── sdk-mode/SKILL.md — SDK detection and build
Key Design Questions
- Loading strategy: Lazy (load skill when needed) vs eager (load all at spawn)?
- Skill interface: What's the contract? Current SKILL.md format or something richer?
- Versioning: How do skill versions interact with squad.agent.md versions?
- Priority vs additive: Can skills override coordinator behavior, or only extend it?
Relationship to Other Work
- SDK-First (feat: \squad init --sdk\ flag for SDK-First mode opt-in #249-251): Skills become
defineSkill()in TypeScript - CLI-First (RFC: CLI-First Architecture — Migrate Squad Automation from GitHub Actions to CLI Commands #252): CLI commands could be skill-backed
- Plugin Marketplace: Skills ARE the plugin format — this makes the coordinator itself pluggable
Acceptance Criteria
- squad.agent.md reduced to <300 lines (core orchestration + skill loading)
- At least 3 coordinator capabilities extracted into skills
- Skill loading is lazy (only loaded when routing matches)
- Existing behavior unchanged (no regressions)
- SDK mode:
defineSkill()generates SKILL.md files
Activity
github-actions commentedon Mar 7, 2026
📋 Assigned to Keaton (Lead)
Issue: #255 — Skill-based orchestration — decompose squad.agent.md into pluggable skills
Keaton will pick this up in the next Copilot session.
bradygaster commentedon Mar 7, 2026
✅ Implemented in commit 412ce58 on dev.
What shipped:
eviewer-protocol\ (~30 lines) — Rejection workflow, strict lockout
Files changed:
Tests: 10 new defineSkill tests in \ est/builders.test.ts. All 3768 tests passing.
— Verbal 🧠
feat: SDK-first squads (#249, #250, #255) + docs (#251)
docs(ai-team): SDK-First implementation completed
feat: add OTel foundation — provider init, telemetry bridge, deps (gi…
docs(ai-team): Merge OTel observability Phase 1 logs and decisions