sdk: squad-commands and squad-version-check missing from squad-sdk templates — silently dropped by squad init on every v0.10.0 install #1289

Summary

squad init on a fresh v0.10.0 install silently drops the squad-commands and squad-version-check skills — the two skills explicitly added in the v0.10.0 release. The user gets 8 skills instead of the 10 listed in MANIFEST_SKILL_NAMES. There is no warning or error.

This is the underlying reason that "squad commands" (a headline v0.10 feature added in #1174) does nothing in any freshly-initialised v0.10.0 project — the skill that handles that intent literally isn't on disk.

Verified on @bradygaster/squad-cli@0.10.0 from npm (latest dist-tag), Windows.

Repro

mkdir test-skill && cd test-skill
squad init
ls .copilot/skills
# Expected: 10 skill directories
# Actual:   8 — squad-commands and squad-version-check are missing

Then in any Copilot session: squad commands — coordinator has no skill to read, so the documented command-discovery menu never appears.

Root cause — three-way mismatch across the monorepo

sdkInitSquad() in @bradygaster/squad-sdk lists 10 skills in MANIFEST_SKILL_NAMES (correct), then copies each one's directory from @bradygaster/squad-sdk/templates/skills/. But only 8 of those 10 source directories exist in the SDK package:

// squad-sdk/dist/config/init.js (~line 948)
for (const skillName of MANIFEST_SKILL_NAMES) {
    const srcSkill = join(skillsSrc, skillName);
    if (storage.existsSync(srcSkill)) {       // ← silent skip when missing
        copyRecursiveSync(srcSkill, join(skillsDir, skillName), storage);
    }
    // no else, no warning
}

Verified at the v0.10.0 tag in the repo:

So both skill source files only exist in one of the three places they need to be:

1. The authoritative source (.squad/skills/{name}/SKILL.md) — missing
2. The squad-sdk template mirror (packages/squad-sdk/templates/skills/{name}/SKILL.md) — missing
3. The squad-cli template mirror (packages/squad-cli/templates/skills/{name}/SKILL.md) — ✅ present

Per the team's documented convention (see .squad/agents/control/history.md):

npm run build calls scripts/sync-skill-templates.mjs which copies .squad/skills/*/SKILL.md files into both packages/squad-sdk/templates/skills/ and packages/squad-cli/templates/skills/. Editing .squad/skills/{name}/SKILL.md is sufficient — the sync propagates it.

#1174 (feat: add squad-commands skill) added the source directly to packages/squad-cli/templates/skills/ without putting an authoritative copy in .squad/skills/, so the sync script had nothing to mirror. Same pattern for squad-version-check. The SDK's templates dir was never populated.

Coordinator impact

• squad commands is a dead trigger phrase on every v0.10.0 install. The routing rule in squad.agent.md says "squad commands" → read .copilot/skills/squad-commands/SKILL.md. That file doesn't exist after squad init, so the coordinator either falls through to a default behaviour or invents one. (Sister to the bug-class catalogued in preset: apply leaves team.md, casting/registry.json, and routing.md unwired — coordinator treats session as Init Mode #1288.)
• Version-check skill is also missing, so the related upgrade-discovery messaging in the session-init flow can't reach users either.
• No diagnostic surface. squad doctor reports all-green because it doesn't validate that every entry in MANIFEST_SKILL_NAMES produced a directory.

Suggested fix

1. Restore the authoritative skill sources

For each missing skill, copy the SKILL.md from packages/squad-cli/templates/skills/ to .squad/skills/:

.squad/skills/squad-commands/SKILL.md
.squad/skills/squad-version-check/SKILL.md

Then run npm run build (which invokes scripts/sync-skill-templates.mjs) to propagate to both packages/squad-sdk/templates/skills/ and packages/squad-cli/templates/skills/. Publish a 0.10.1 patch.

2. Add a CI guard against silent drift

Add a build-time check that:

• Every name in MANIFEST_SKILL_NAMES has a corresponding directory in packages/squad-sdk/templates/skills/ (or fail the build).
• Every name in TEMPLATE_MANIFEST (CLI) has a corresponding source file in packages/squad-cli/templates/skills/ (or fail the build).
• The sets in CLI's TEMPLATE_MANIFEST skill entries and SDK's MANIFEST_SKILL_NAMES agree.

A single Node test that walks both manifests and asserts source presence would have caught this before v0.10.0 shipped.

3. Stop the silent skip

In sdkInitSquad() skill-copy loop, replace:

if (storage.existsSync(srcSkill)) {
    copyRecursiveSync(srcSkill, join(skillsDir, skillName), storage);
}

with something that logs (or warns into the init output and the returned warnings array):

if (storage.existsSync(srcSkill)) {
    copyRecursiveSync(srcSkill, join(skillsDir, skillName), storage);
} else {
    warnings.push(`Manifest skill '${skillName}' has no source in templates/skills/ — skipped.`);
}

This would surface drift the moment it ships, instead of weeks later when a user notices squad commands is a no-op.

4. squad doctor enhancement

Add a check that compares .copilot/skills/ contents against MANIFEST_SKILL_NAMES (resolved from the installed SDK) and fails if any manifest skill is missing on disk. Suggested message:

"Manifest skill 'squad-commands' is missing from .copilot/skills/ — run squad upgrade or reinstall to refresh skills."

Environment

• @bradygaster/squad-cli@0.10.0 from npm (latest)
• @bradygaster/squad-sdk (nested under squad-cli)
• Node v23.5.0, Windows 11
• Non-git directory (C:\temp\squad-skill)

Workaround until 0.10.1

# Pull the missing skills directly from the v0.10.0 tag
mkdir -p .copilot/skills/squad-commands .copilot/skills/squad-version-check
curl -L https://raw.githubusercontent.com/bradygaster/squad/v0.10.0/packages/squad-cli/templates/skills/squad-commands/SKILL.md -o .copilot/skills/squad-commands/SKILL.md
curl -L https://raw.githubusercontent.com/bradygaster/squad/v0.10.0/packages/squad-cli/templates/skills/squad-version-check/SKILL.md -o .copilot/skills/squad-version-check/SKILL.md

Related

• feat: add squad-commands skill #1174 — feat: add squad-commands skill (PR that introduced the gap)
• docs(skills): document .copilot/skills/ canonical path + .squad/skills/ fallback #1242 / docs(skills): docs say .squad/skills/ but code writes to .copilot/skills/ — pick one and clarify #1241 — docs/skill-path drift (separate concern; this issue is about missing source files, not pathing)
• preset: apply leaves team.md, casting/registry.json, and routing.md unwired — coordinator treats session as Init Mode #1288 — preset: apply leaves team.md, casting/registry.json, and routing.md unwired (sister symptom — v0.10.0 init pipeline has multiple silent gaps; both bugs share the "no diagnostic surface in squad doctor" theme)