feat: add squad-commands skill by tamirdresher · Pull Request #1174 · bradygaster/squad

tamirdresher · 2026-05-26T14:00:46Z

Summary

Ship a first-party squad-commands skill so that every squad init and squad upgrade drops a categorized command catalog into .squad/skills/squad-commands/SKILL.md. Users can say "squad commands", "help", or "what can squad do?" and the coordinator presents an interactive category-level menu, then drills into the selected category.

This implements the design proposed in issue #1172.

What Changed

File	Change
`packages/squad-cli/templates/skills/squad-commands/SKILL.md`	New — full catalog of 22 operations in 6 categories
`packages/squad-cli/src/cli/core/templates.ts`	Added TEMPLATE_MANIFEST entry with `overwriteOnUpgrade: true`
`packages/squad-cli/templates/squad.agent.md.template`	Added routing table row + greeting tip instruction
`.github/agents/squad.agent.md`	Same routing row + greeting tip applied to live coordinator
`README.md`	Added "Quick Commands" section (3 lines)

Design Decisions

Three decisions were applied as implementation defaults:

Greeting tip on a separate line — not appended to the version stamp. Cleaner, avoids long single-line greetings.
"help" (standalone) routes to this skill — the squad-commands skill IS the help system. "help me with X" still routes as a general work request.
overwriteOnUpgrade: true — first-party catalog, versions with the CLI. Users who want custom commands create their own skill file.

Skill Structure

The SKILL.md uses a coordinator-readable schema: YAML frontmatter with triggers list, then ## Category / ### Operation blocks with structured fields:

intent — matched against user utterance
summary — ≤80 chars, shown in the menu
action — shell, coordinator, or file-edit
command — literal CLI command or coordinator procedure
args — ordered list with prompt, optional choices, optional default
confirm — true for destructive operations
platform_caveats — surface-specific notes (CLI-only ops, VS Code behavior)

Categories: Install & Upgrade · Team Management · Issues & PRs · Plugins & Skills · Model & Cost · Sessions & State

Acceptance Criteria

#	Criterion	File
AC-1	`squad-commands` SKILL.md in install template	`packages/squad-cli/templates/skills/squad-commands/SKILL.md`
AC-2	Coordinator routes intent signals to this skill	routing row in `squad.agent.md.template` + live `squad.agent.md`
AC-3	Menu grouped by category, uses `ask_user`	Menu Presentation Rules section in `SKILL.md`
AC-4	Selection → run or minimum follow-up questions	`args` fields + argument collection rules in `SKILL.md`
AC-5	Documented in README	"Quick Commands" section in `README.md`

Coordinator Restart Note

If you are in an active Squad session when you pull this change, restart your Copilot session so the coordinator picks up the updated squad.agent.md with the new routing row.

Ship a first-party \squad-commands\ skill so that every \squad init\ and \squad upgrade\ drops a categorized command catalog into \.squad/skills/squad-commands/SKILL.md\. Users can say 'squad commands', 'help', or 'what can squad do?' and the coordinator presents an interactive category-level menu, then drills into the selected category. ## What changes - \packages/squad-cli/templates/skills/squad-commands/SKILL.md\ (new) Full catalog of 22 operations in 6 categories: Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State. Each entry carries: intent, summary (<=80 chars), action, command, args with prompts/choices/defaults, confirm flag, and platform_caveats. - \packages/squad-cli/src/cli/core/templates.ts\ Added TEMPLATE_MANIFEST entry for the new skill with overwriteOnUpgrade: true so CLI upgrades keep the catalog current. - \packages/squad-cli/templates/squad.agent.md.template\ Added routing table row (after Ralph commands, before General work request) for trigger phrases: 'squad commands', 'what can squad do', 'help' (standalone), 'show me squad options', 'slash commands'. Added greeting tip instruction: separate line after version stamp, directing new users to say 'squad commands'. - \.github/agents/squad.agent.md\ Same routing row and greeting tip applied to the live coordinator so the change is immediately effective in this repo. - \README.md\ Added 'Quick Commands' section (3 lines) describing the in-chat discovery mechanism. ## Design decisions (per Tamir Dresher) - Greeting tip on a separate line, not appended to the version stamp (cleaner) - 'help' (standalone) routes to this skill — it IS the help system - overwriteOnUpgrade: true — first-party catalog, no user customization in v1 ## Acceptance criteria mapping (issue #1172) - AC-1: SKILL.md exists in install template → packages/squad-cli/templates/skills/squad-commands/SKILL.md - AC-2: Coordinator routes intent signals to this skill → routing row in squad.agent.md.template + live squad.agent.md - AC-3: Menu grouped by category, uses ask_user → Menu Presentation Rules section in SKILL.md - AC-4: Selection → run or minimum follow-up questions → args fields + argument collection rules in SKILL.md - AC-5: Documented in README → Quick Commands section in README.md Proposed by: Picard (Lead / Product Architect), design at .squad/decisions/inbox/picard-issue-2-squad-commands-design.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds a new first-party squad-commands skill intended to provide in-chat discovery of common Squad operations via a categorized menu, and wires the coordinator + templates to route “help / squad commands” style intents to that catalog.

Changes:

Added a new squad-commands SKILL.md catalog template.
Wired the CLI template manifest + coordinator routing to surface the new catalog.
Documented the feature in README.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
`packages/squad-cli/templates/skills/squad-commands/SKILL.md`	New skill content defining menu rules + categorized operations list
`packages/squad-cli/src/cli/core/templates.ts`	Adds the skill to the CLI template manifest for upgrade/install syncing
`packages/squad-cli/templates/squad.agent.md.template`	Updates coordinator prompt/routing to point users at the command catalog
`.github/agents/squad.agent.md`	Applies the same coordinator routing + greeting tip to the live agent prompt
`README.md`	Adds a short “Quick Commands” section advertising the new capability

  },
+  {
+    source: 'skills/squad-commands/SKILL.md',
+    destination: 'skills/squad-commands/SKILL.md',


+  {
+    source: 'skills/squad-commands/SKILL.md',
+    destination: 'skills/squad-commands/SKILL.md',
+    overwriteOnUpgrade: true,
+    description: 'In-chat command discovery — categorized menu of Squad operations',



 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating


 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "help" (standalone), "show me squad options", "slash commands" | Read `.squad/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |



 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating


 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "help" (standalone), "show me squad options", "slash commands" | Read `.squad/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |


+triggers:
+  - "squad commands"
+  - "what can squad do"
+  - "show me squad options"
+  - "help"
+  - "slash commands"
+  - "what commands are available"
+  - "how do I"


+  - "help"
+  - "slash commands"
+  - "what commands are available"
+  - "how do I"
+---
+
+## Menu Presentation Rules
+
+When the user triggers this skill ("squad commands", "help", "what can squad do", etc.):


…ME guidance to spawn-reference - Add .changeset/squad-commands-skill.md to satisfy Policy Gate (templates.ts changed) - Rename step 5 in scribe-charter.md to 'Commit and verify persistence' to fix scribe-template CI test failures (commit step was missing from numbered task list) - Add CURRENT_DATETIME substitution guidance to spawn-reference.md step 1 to fix datetime-template CI test (literal CURRENT_DATETIME string was removed in state tools refactor but test still requires it) Pre-existing failures on upstream/dev — not caused by this PR's feature changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Install squad-commands to .copilot/skills (not .squad/skills) so squad init and the skill loader find it consistently - Add squad-commands to SDK MANIFEST_SKILL_NAMES so squad init installs it - Move routing edits to canonical .squad-templates/squad.agent.md and re-run sync to regenerate all 4 mirrors - Fix frontmatter triggers to inline-array form (parseFrontmatter only supports inline arrays) - Drop generic trigger words to avoid substring collisions with unrelated tasks - Add changeset entry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…gger normalization for Copilot integration Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ot/skills path CAPCOM-3's clean-redo deleted the routing entry and greeting tip while addressing the path correction. This restores them in the canonical template (.squad-templates/squad.agent.md) with the corrected .copilot/skills/squad-commands/SKILL.md path and trimmed triggers (dropped generic 'help'), then re-syncs to the 4 mirror surfaces. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat: session init update check + extensible session-init reference (#1173) Closes #1173 - Adds Session Init phase to coordinator (squad.agent.md + template); Step 1 is the Update Check, which runs silently at session start and appends a version notice to the greeting when a newer release exists for the user's channel. - Adds reusable session-init-reference.md installed to .squad/templates/ so future init steps (dependency drift check, state-backend audit) can be added without modifying the coordinator prompt. - Reuses upstream self-update.ts cache (OS-specific, 24h TTL) for latest-channel users; falls back to npm view dist-tags for insider/preview channels with a repo-local .squad/.cache/version-check.json cache. - Respects SQUAD_NO_UPDATE_CHECK=1 kill switch (same opt-out as CLI banner). - Routing table updated: upgrade squad / update squad / what's new in squad / install the update intents route to the upgrade flow in session-init-reference.md. - Adds squad-version-check SKILL.md (CLI internals knowledge) to install template and TEMPLATE_MANIFEST with overwriteOnUpgrade: true. - Adds .squad/.cache/ to .gitignore. Design reviewed by Picard (coordinator architecture); implementation follows the pattern established in PR #1174 (squad-commands skill). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: add changeset, commit step to scribe-charter, and CURRENT_DATETIME guidance to spawn-reference - Add .changeset/session-init-version-check.md to satisfy Policy Gate (templates.ts changed) - Rename step 5 in scribe-charter.md to 'Commit and verify persistence' to fix scribe-template CI test failures (commit step was missing from numbered task list) - Add CURRENT_DATETIME substitution guidance to spawn-reference.md step 1 to fix datetime-template CI test (literal CURRENT_DATETIME string was removed in state tools refactor but test still requires it) Pre-existing failures on upstream/dev — not caused by this PR's feature changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(sdk): register squad-version-check in MANIFEST_SKILL_NAMES and add .squad/.cache/ to init ignoreEntries (#1175) - Add 'squad-version-check' to MANIFEST_SKILL_NAMES so squad init installs it - Include '.squad/.cache/' in ignoreEntries to prevent caching artifacts in git Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(cli): add .squad/.cache/ to upgrade GITIGNORE_ENTRIES (#1175) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(skill): update Node version requirement to 22.5.0 in squad-version-check SKILL.md (#1175) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 26, 2026 14:00

Copilot started reviewing on behalf of tamirdresher May 26, 2026 14:01 View session

Copilot AI reviewed May 26, 2026

View reviewed changes

tamirdresher mentioned this pull request May 26, 2026

feat: session init update check (#1173) #1175

Merged

bradygaster approved these changes May 26, 2026

View reviewed changes

fix: add squad-commands skill routing, MANIFEST registration, and tri…

0cb3835

…gger normalization for Copilot integration Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher force-pushed the squad/1172-squad-commands-skill branch from 8321fb8 to 0cb3835 Compare May 26, 2026 19:08

ci: trigger workflow re-run

c191f77

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher closed this May 26, 2026

tamirdresher reopened this May 26, 2026

ci: re-trigger workflow under non-bot author

bc3b319

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add squad-commands skill#1174

feat: add squad-commands skill#1174
tamirdresher wants to merge 6 commits into
devfrom
squad/1172-squad-commands-skill

tamirdresher commented May 26, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

tamirdresher commented May 26, 2026

Summary

What Changed

Design Decisions

Skill Structure

Acceptance Criteria

Coordinator Restart Note

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants