Repository navigation
Skills in .copilot/skills/ are invisible to all Copilot surfaces except Squad #1126
Description
Summary
Skills in .copilot/skills/ are invisible to all GitHub Copilot surfaces except Squad itself. The official Agent Skills spec places project-level skills in .github/skills/, .claude/skills/, or .agents/skills/ -- .copilot/skills/ at repo root is not a recognized location.
This means Squad-created skills don't work with:
- GitHub Copilot cloud agent
- Copilot CLI (outside Squad)
- VS Code Copilot extension (agent mode)
@copilotcoding agent on issues- Any future Copilot surface
Evidence -- Three Independent Sources Verified
| Source | Project skills (repo-level) | Personal skills (user-level) |
|---|---|---|
| GitHub docs -- About Agent Skills | .github/skills/, .claude/skills/, .agents/skills/ |
~/.copilot/skills/, ~/.agents/skills/ |
| GitHub docs -- Add Skills | .github/skills/, .claude/skills/, .agents/skills/ |
~/.copilot/skills/, ~/.agents/skills/ |
| VS Code docs -- Agent Skills | .github/skills/, .claude/skills/, .agents/skills/ |
~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/ |
.copilot/skills/ (repo root) does not appear in any official documentation.
Source of Confusion
~/.copilot/skills/ (home directory) is valid for personal skills. .copilot/skills/ (repo root) looks like the project-level equivalent -- but it isn't. The actual project-level path is .github/skills/.
The .github/skills/ path is the universal project-level location for the Agent Skills open standard, which Copilot, Claude, and other agents all share. .claude/skills/ exists as an alternative format, not as evidence that each tool gets its own repo-root directory.
Top Threats
1. Customer mental model confusion
.copilot/skills/ at repo root creates an internally consistent but incorrect mental model. Customers who learn ~/.copilot/skills/ (personal) will predict .copilot/skills/ (project) -- and nothing in their experience corrects them, because Squad makes it work via hardcoded paths. This teaches every new Squad user the wrong convention.
2. Skills invisible to current and future Copilot surfaces
Every Copilot surface -- cloud agent, CLI, VS Code, @copilot coding agent, code review -- discovers from .github/skills/. As GitHub ships more Copilot-powered experiences, the gap between what Squad customers expect and what actually works widens. Customers who invest in writing skills discover they are invisible everywhere except their local Squad session.
Prior Art
- PRD: Migrate Squad Skills from .squad/skills/ to .copilot/skills/ #354 -- Original migration PRD (
.squad/to.copilot/). A commenter noted: "project/repo level skills are actually only found when located at.github/skillsor.claude/skills" - Are skills correctly placed in .copilot/skills? #589 -- Questioned whether
.copilot/skills/is correct. Closed as by-design. - bug: squad.agent.md SKILL EXTRACTION still directs to legacy .squad/skills/ path (follow-up to #354) #869 -- Follow-up noting
squad.agent.mdstill referenced legacy.squad/skills/
Proposed Fix
- Move project-level skills from
.copilot/skills/to.github/skills/ - Update
squad.agent.mdskill-aware routing to check.github/skills/(primary) and.squad/skills/(team-discovered patterns) - Add a migration note or backward-compat shim for existing repos
This makes Squad skills portable across the entire Copilot ecosystem while preserving .squad/skills/ for team-discovered patterns.
Activity
bradygaster commentedon May 18, 2026
@diberry @spboyer @tamirdresher can we confirm this? we deliberately moved them to their currently location from
.squadthinking they'd become available.also, i am not sure i want squad-created skills available to non-squad copilot functionality.
diberry commentedon May 18, 2026
@bradygaster I'm not concerned with .squad skills. Only the other skills.
dat-intellis commentedon May 18, 2026
This comment in your description does not seem correct:
"The .github/skills/ path is the universal project-level location for the Agent Skills open standard, which Copilot, Claude, and other agents all share."
Should it have been
.agents/skills/perhaps? Which seems to be the broadest supported path in harnesses.Not sure if that is supported by Claude though - they seem pretty intent on only using .claude/skills. I think there might be an --add-dirs flag which could be utilised in that case.
diberry commentedon May 20, 2026
@dat-intellis Thank you for that correction.
Merge PR github#1304: skills to .github/skills/ (closes github#1126)
fix: squad_skill writes to .github/skills, sync .github/agents copy, …
Merge PR github#1304: skills to .github/skills/ (closes github#1126)
fix(skills): install bundled skills to .github/skills/ (closes github…
fix: squad_skill writes to .github/skills, sync .github/agents copy, …
test(init): update squad-help + /squad slash test paths to .github/sk…
fix(skills): install bundled skills to .github/skills/ (closes #1126) (…