PRD: Migrate Squad Skills from .squad/skills/ to .copilot/skills/ #354

PRD: Migrate Squad Skills from .squad/skills/ to .copilot/skills/

Problem Statement

Squad currently writes and reads skills from .squad/skills/{name}/SKILL.md. This is the wrong location. GitHub Copilot's skill discovery system reads from .copilot/skills/ ΓÇö that's where Copilot looks for skills to load into agent context. The current placement means:

1. Skills are invisible to Copilot. Agents create skills during work but Copilot never discovers them in future sessions because it's not scanning .squad/skills/.
2. Other Copilot features can't use Squad skills, and vice-versa. A user who installs a Copilot skill (e.g., azure-ai) into .copilot/skills/ gets no benefit from it in Squad sessions because Squad only checks .squad/skills/.
3. Performance penalty from full-content scanning. Shayne Boyer's analysis suggests that skills in .squad/skills/ are being scanned in their entirety (full SKILL.md content) rather than just frontmatter, because they're not in the canonical location where Copilot optimizes skill loading. Moving to .copilot/skills/ would let Copilot handle discovery and indexing optimally.
4. Inconsistency with Copilot ecosystem conventions. The .copilot/ directory is the established namespace for Copilot configuration (mcp-config.json, skills/, etc.). Having skills split across two directories creates confusion.

Upstream Issues (bradygaster/squad)

This PRD consolidates findings from the following issues and PRs in the Squad source repo:

Primary ΓÇö Direct Skill Location Issues

Secondary ΓÇö Skill System Architecture

Tertiary ΓÇö Personal Squad & Path Resolution

Context ΓÇö Memory & Context Window

Proposed Changes

1. Change skill write path from .squad/skills/ to .copilot/skills/

All locations where agents create or reference skills must change.

squad.agent.md ΓÇö 6 references to update:

1. Skill-aware routing (line ~231): .squad/skills/ ΓåÆ .copilot/skills/
2. MCP integration reference (line ~451): .squad/skills/mcp-tool-discovery/SKILL.md ΓåÆ .copilot/skills/mcp-tool-discovery/SKILL.md
3. Spawn template ΓÇö skill read (line ~646): If .squad/skills/ has relevant SKILL.md files ΓåÆ If .copilot/skills/ has relevant SKILL.md files
4. Spawn template ΓÇö AFTER work / skill extraction (line ~668): .squad/skills/{skill-name}/SKILL.md ΓåÆ .copilot/skills/{skill-name}/SKILL.md
5. Adding Team Members ΓÇö marketplace plugin install (line ~753): .squad/skills/{plugin-name}/SKILL.md ΓåÆ .copilot/skills/{plugin-name}/SKILL.md
6. Plugin Marketplace core rules (line ~776): .squad/skills/{plugin-name}/SKILL.md ΓåÆ .copilot/skills/{plugin-name}/SKILL.md

Source of Truth Hierarchy ΓÇö remove .squad/skills/ row or redirect

The Source of Truth table lists .squad/skills/ as readable by agents. This should point to .copilot/skills/ instead.

Template files:

• .squad/templates/skill.md ΓÇö update any path references
• .squad/templates/mcp-config.md ΓÇö update .squad/skills/mcp-tool-discovery/SKILL.md reference
• .squad/templates/plugin-marketplace.md ΓÇö update .squad/skills/{plugin-name}/SKILL.md reference

Skill files with internal cross-references:

• .squad/skills/content-validation/SKILL.md ΓÇö 5 internal .squad/skills/ references to other skills

Agent charters and histories:

• Multiple agent history.md and charter.md files reference .squad/skills/ (32+ references across the codebase)

2. Upgrade migration ΓÇö move existing skills on next upgrade

When a user upgrades Squad (via npx github:bradygaster/squad or squad upgrade), the upgrade flow should:

1. Detect existing skills at .squad/skills/
2. Create .copilot/skills/ if it doesn't exist
3. Move each {skill-name}/SKILL.md from .squad/skills/ to .copilot/skills/
4. Leave a marker or symlink at .squad/skills/ pointing to .copilot/skills/ (grace period for agents running stale instructions)
5. Update internal path references in the moved SKILL.md files (cross-references between skills)
6. Report what was migrated: "📦 Migrated {N} skills from .squad/skills/ → .copilot/skills/"

Backward compatibility: For one version after the change, the coordinator should check BOTH locations ΓÇö .copilot/skills/ (primary) and .squad/skills/ (fallback) ΓÇö to handle repos that haven't upgraded yet. After one version, drop the fallback.

3. Prompt user to reload after skill creation

After any agent creates or updates a skill, the Coordinator should prompt:

📌 New skill created: {skill-name}
   Reload your Copilot session to make it available, or it will be picked up next session.

This ensures skills are immediately actionable rather than silently created.

4. Update .gitignore considerations

Skills in .copilot/skills/ should be committed to the repo (they're project knowledge). The .copilot/ directory already exists for mcp-config.json. No .gitignore changes needed for project-level skills.

For personal squads using consult mode, skills in the personal squad's .copilot/skills/ stay in the personal squad directory (not copied to project).

5. Three-layer skill awareness (from #330)

After the move, the coordinator should understand three distinct skill layers:

All three should be visible to the coordinator during routing and passed to agents when relevant.

6. SDK/CLI code changes (in bradygaster/squad repo)

• packages/squad-sdk/src/resolution.ts ΓÇö skill path resolution
• SkillScriptLoader ΓÇö path references for handler script discovery
• squad init ΓÇö create .copilot/skills/ instead of .squad/skills/ during init
• squad upgrade ΓÇö migration logic (detect, move, update references)
• squad export / squad import ΓÇö handle both locations, export from .copilot/skills/
• squad doctor ΓÇö validate skills are in correct location

Impact Analysis

Files affected in this repo (bradyland)

Performance benefits (from @spboyer's analysis, #330)

• Copilot's skill system reads frontmatter for discovery, full content only when matched. In .squad/skills/, Squad reads ALL SKILL.md files fully during routing.
• With 23 skills averaging ~5KB each, that's ~115KB of skill content loaded into context on every spawn routing decision.
• Moving to .copilot/skills/ lets Copilot handle indexing ΓÇö only frontmatter scanned for routing, full content loaded only for matched skills.

Breaking changes

• None for end users ΓÇö migration is automatic on upgrade.
• Stale coordinator instructions ΓÇö repos running an older squad.agent.md will still reference .squad/skills/. The backward-compatibility fallback handles this during the transition period.
• Custom agent charters ΓÇö users who manually reference .squad/skills/ in their charters will need to update (Shayne's exact pain point in How to let agents use current custom skills? #153).

What stays in .squad/

Everything else stays. Only skills move:

• Γ£à .squad/agents/ ΓÇö charters, history (stays)
• Γ£à .squad/decisions.md ΓÇö decisions (stays)
• Γ£à .squad/casting/ ΓÇö name registry (stays)
• Γ£à .squad/templates/ ΓÇö format guides (stays)
• Γ£à .squad/ceremonies.md ΓÇö dispatch table (stays)
• Γ£à .squad/log/, .squad/orchestration-log/ ΓÇö logs (stays)
• ≡ƒöä .squad/skills/ ΓåÆ .copilot/skills/ ΓÇö moves

Acceptance Criteria

• All 6 .squad/skills/ references in squad.agent.md updated to .copilot/skills/
• Template files updated (skill.md, mcp-config.md, plugin-marketplace.md)
• Upgrade flow detects .squad/skills/ and migrates to .copilot/skills/
• Backward-compat fallback: coordinator checks both locations for one version
• Agent spawn template AFTER work section points to .copilot/skills/
• Skill cross-references within SKILL.md files updated
• Export/import handles .copilot/skills/ as the canonical location
• squad doctor validates skills are in .copilot/skills/
• Post-creation reload prompt added to coordinator
• Three-layer skill awareness documented in coordinator instructions
• All existing skills in bradyland moved from .squad/skills/ to .copilot/skills/
• Agent histories and charters updated with new paths
• No regression in skill routing ΓÇö skills still matched and loaded correctly
• Personal squad skill portability works with new path

References

• bradygaster/squad#353 ΓÇö Primary issue (Shayne Boyer)
• bradygaster/squad#330 ΓÇö Three-layer tooling model (Shayne Boyer)
• bradygaster/squad#153 ΓÇö User pain: custom skills invisible to Squad (sturlath)
• bradygaster/squad#255 ΓÇö Skill-based orchestration architecture
• bradygaster/squad#193 ΓÇö Ceremony skills (Will Breza)
• bradygaster/squad#344 ΓÇö Personal squad skill awareness (James Sturtevant)
• bradygaster/squad#329 ΓÇö Personal squad multi-team support
• bradygaster/squad#297 ΓÇö EmmittJ skill system credit
• bradygaster/squad PR#325 ΓÇö SkillScriptLoader implementation
• bradygaster/squad#82 ΓÇö Skill export/import preservation
• bradygaster/squad#63 ΓÇö Memory system / context window pressure