docs(skills): docs say .squad/skills/ but code writes to .copilot/skills/ — pick one and clarify #1241

Summary

The published Skills documentation says skills live at .squad/skills/{name}/SKILL.md, but the actual code (CLI commands, SDK tool, SkillSource fetcher, sharing/consult, squad init) all write skills to .copilot/skills/{name}/SKILL.md. Both paths are scanned at read time per squad.agent.md precedence rules, but writes diverge from what the docs describe.

This creates real confusion: a user who follows the docs writes to .squad/skills/; then the same user invokes any CLI or agent-driven skill write, and ends up with skills in two directories with the .squad/skills/ one shadowing the .copilot/skills/ one.

Code says: .copilot/skills/ is the write default

• packages/squad-cli/src/cli/commands/skill.ts:75-91 — resolveSkillsDir() explicitly prefers .copilot/skills/. Comment: "Resolve the skills directory, preferring .copilot/skills/ over .squad/skills/.". New installs default to .copilot/skills/.
• packages/squad-sdk/src/tools/index.ts:1087, 1164 — SDK skill tool description and write confirmation both say .copilot/skills/{name}/SKILL.md.
• packages/squad-sdk/src/tools/index.ts:125 — field doc: "Skill name (maps to .copilot/skills/{name}/SKILL.md)".
• packages/squad-sdk/src/skills/skill-source.ts:139 — pathPrefix default: '.copilot/skills'.
• packages/squad-sdk/src/sharing/consult.ts:183, 1011, 1040 — sharing/consult routes skills to .copilot/skills/.
• packages/squad-sdk/src/config/init.ts:1189 — squad init creates .copilot/skills.

Docs still say: .squad/skills/

• docs/src/content/docs/features/skills.md:28 — .squad/skills/{skill-name}/SKILL.md (without mentioning .copilot/skills/)
• docs/src/content/docs/features/skills.md:95 — example path uses .squad/skills/ci-github-actions/SKILL.md
• docs/src/content/docs/features/skills.md:120 — "stored in a flat .squad/skills/ directory" — direct contradiction of CLI behavior
• docs/src/content/docs/concepts/portability.md:67, 104, 129, 149, 154, 178 — multiple references to .squad/skills/ as canonical

State + scan still reference .squad/skills/

• packages/squad-sdk/src/state/schema.ts:27 — StatePathMap: skills: (id) => .squad/skills/${id}
• packages/squad-sdk/src/state/collections.ts:249-251 — listSkillIds() reads from .squad/skills/
• .github/agents/squad.agent.md skill-aware routing — scans 5 paths in precedence; .squad/skills/ is HIGHEST.

So the runtime is in a partial transition: writes go new (.copilot/skills/), reads + state plumbing still know about old (.squad/skills/).

Verification note

session-recovery skill currently EXISTS at .squad/skills/session-recovery/SKILL.md — so the doc link at line 60 is valid. However, the surrounding description of where skills live is still incorrect.

Decision needed

One of two paths makes the docs honest:

Option A — .copilot/skills/ is canonical (matches the code's write direction)

• Update the Skills docs to teach .copilot/skills/
• Keep .squad/skills/ as a "legacy fallback" with a deprecation note
• Plan migration: existing .squad/skills/ content gets moved during squad upgrade

Option B — .squad/skills/ is canonical (matches the precedence rule + state schema)

• Revert the CLI/SDK write target to .squad/skills/
• Keep .copilot/skills/ as a discovery-only scan path (no writes)
• Update resolveSkillsDir() to prefer .squad/skills/

The follow-up PR will go with Option A by default (since it matches what squad init already creates and what the SDK tool already writes), but will leave the decision visible so maintainers can choose Option B if they prefer.

Acceptance criteria

• docs/src/content/docs/features/skills.md describes the SAME path users see when they run CLI/SDK skill commands.
• Doc explains the precedence/scan behavior (5 paths, dedup rule) so users understand the read story even when most writes go to one place.
• If .squad/skills/ content moves to .copilot/skills/ (Option A), state schema reference is updated accordingly OR an explicit "legacy fallback" doc note explains the read-only role.
• docs/src/content/docs/concepts/portability.md is also updated — it references .squad/skills/ at 6+ locations.

Related

• The docs/src/content/docs/concepts/portability.md document references both paths — needs the same treatment as features/skills.md.