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

[bradygaster]

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

#	Title	Status	Author	Relevance
#353	feat: skills should be created in .copilot/skills/ and prompt user to reload	Open	@spboyer	Core request. Change write path, update spawn template, add migration, prompt reload after creation.
#330	Coordinator should detect and enforce all three tooling layers (local skills, global MCP, global Copilot skills)	Open	@spboyer	Three-layer model. Squad has zero awareness of global Copilot skills (<available_skills>). Moving to .copilot/skills/ unifies local and global skills into one discovery path. Documented 11 of 13 deployment fix commits were avoidable.
#153	How to let agents use current custom skills?	Closed	@sturlath	User pain. User had skills in .github/agents/skills/ and couldn't figure out how to make Squad see them. Had to manually add paths to every charter. Moving to .copilot/skills/ makes all skills discoverable by default.

Secondary ΓÇö Skill System Architecture

#	Title	Status	Author	Relevance
#255	Skill-based orchestration ΓÇö decompose squad.agent.md into pluggable skills	Closed	@bradygaster	Proposed moving coordinator capabilities into skills. Path change affects where these would live.
#193	Ceremonies break when ceremonies.md exceeds file-size threshold ΓÇö migrate to skill-based dispatch	Closed	@wbreza	Proposed ceremony skills in .squad/skills/ceremony-*/. Path change means these become .copilot/skills/ceremony-*/.
#297	Credit EmmittJ for skill system inspiration + follow-up issues from PR #215	Open	@bradygaster	Skill handler scripts (SkillScriptLoader) reference .squad/skills/ paths.
PR #325	feat(skills): add SkillScriptLoader, handler types, and applySkillHandlers	Open	ΓÇö	Runtime skill loader scans .squad/skills/{name}/scripts/ for JS handlers. Path references need updating.
#82	Verify skills are preserved during export/import	Closed	ΓÇö	Export/import must handle the new path. Skills earned pre-migration in .squad/skills/ need migration during import too.

Tertiary ΓÇö Personal Squad & Path Resolution

#	Title	Status	Author	Relevance
#344	Governance layer has no awareness of personal squad paths	Open	@jsturtevant	Personal squads have skills that should be portable across projects. .copilot/skills/ is already a user-level concept.
#329	Personal Squad updates	Open	ΓÇö	Multi-team support proposal. Skills portability between personal squads and projects is a key use case.
#343	Personal squad docs reference ~/.squad/ instead of platform-specific paths	Open	ΓÇö	Documentation path references need updating alongside skill path changes.

Context ΓÇö Memory & Context Window

#	Title	Status	Author	Relevance
#63	Memory System Improvements ΓÇö Feedback Welcome	Closed	ΓÇö	Context window pressure from loading all skills. Moving to .copilot/skills/ lets Copilot handle discovery efficiently (frontmatter-only scanning).
#37	Context window optimization: decisions.md pruning, spawn template dedup	Closed	ΓÇö	Related optimization work. Skills contribute to context bloat when fully scanned.

---

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:

Layer	Location	Scope	Discovery
Project skills	.copilot/skills/	This repo	Copilot auto-discovers
Global Copilot skills	<available_skills> environment	User-wide	Copilot provides at runtime
Personal squad skills	{personal-squad-root}/.copilot/skills/	Cross-project	Via consult mode

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)

Category	Count	Details
.github/agents/squad.agent.md	6 refs	Coordinator governance ΓÇö all skill path references
.squad/templates/*.md	3 files	squad.agent.md, mcp-config.md, plugin-marketplace.md
.squad/skills/*/SKILL.md	23 skills	Must be physically moved to .copilot/skills/
.squad/agents/*/history.md	10+ files	Path references in learnings sections
.squad/agents/*/charter.md	3+ files	Charter skill references
.squad/decisions.md	9 refs	Historical decision references
docs/**/*.md	6+ files	Documentation referencing .squad/skills/

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

• feat: skills should be created in .copilot/skills/ and prompt user to reload #353 ΓÇö Primary issue (Shayne Boyer)
• Coordinator should detect and enforce all three tooling layers (local skills, global MCP, global Copilot skills) #330 ΓÇö Three-layer tooling model (Shayne Boyer)
• How to let agents use current custom skills? #153 ΓÇö User pain: custom skills invisible to Squad (sturlath)
• Skill-based orchestration — decompose squad.agent.md into pluggable skills #255 ΓÇö Skill-based orchestration architecture
• Ceremonies break silently when ceremonies.md exceeds file-size threshold — migrate to skill-based dispatch #193 ΓÇö Ceremony skills (Will Breza)
• Governance layer has no awareness of personal squad paths #344 ΓÇö Personal squad skill awareness (James Sturtevant)
• Personal Squad updates #329 ΓÇö Personal squad multi-team support
• Credit EmmittJ for skill system inspiration + create follow-up issues from PR #215 #297 ΓÇö EmmittJ skill system credit
• bradygaster/squad PR#325 ΓÇö SkillScriptLoader implementation
• Verify skills are preserved during export/import and document skill-agent associations #82 ΓÇö Skill export/import preservation
• Memory System Improvements — Feedback Welcome #63 ΓÇö Memory system / context window pressure

[CarlosSardo]

Nudging to #355