Are skills correctly placed in .copilot/skills? #589

Activity

1. jackusm commented on Mar 25, 2026

   

   jackusm

   on Mar 25, 2026

   More actions

   Note: I only use the squad CLI for install/upgrade (I launch copilot-cli directly after setup), so it's possible this skills location issue is a non issue when used that way by pointing to them directly, I wouldn't know about that.

   After upgrading, skills were duplicated into .copilot (and left unused). The squad agent still reads every skill, entirely, from .squad/skills and scribe still writes and changes from there also, which further causes agents to continue to load the whole skill files into context. Removing them from .squad and putting them into to .github fixes this - skills are then used correctly without loading every file. I had to update many instructions to use the skills tool instead from reading the full file paths.

   As a fix to this, it may be worth pushing scribe to migrate/cleanup on its next run after an upgrade (for example, to tell agents to use the skills tool with specific skills where this happens, rather than specifying full paths to read them from as regular files). This could also help improve updating across the board, such as when updating model/ranking or model-selection configs to use the new skill to do so, helping avoid any stale/conflicting settings across all future upgrades.

   For example opus 4.5 used to be a default, and if you search the .squad folder there are many lingering references to using it any of our own repos, and even in this repo, and not just as a fallback. Aside from that, the fallback/model ranking explanation itself, is duplicated as many as 5 or more times with only the skill actually being the most up to date. If you tell Squad to re-order priorities, it often ignores that because only 2/5 tables were changed.

   Using LLM to self upgrade always ends up with issues such as this, which end up further polluting contexts. I'm not sure how to solve that except manually, since it wouldn't be an issue if the models were doing it themselves thoroughly enough in the first place ^^
2. bradygaster commented on Mar 26, 2026

   

   bradygaster

   on Mar 26, 2026

   Collaborator

   More actions

   Thanks for surfacing this, @sturlath and @jackusm! Both observations are spot-on and help us sharpen how we communicate this.

   Here's what's actually happening:

   The two-directory design is intentional

   • .copilot/skills/ (17 skills) = process-level capabilities. These are the canonical location for Squad—it's a GitHub Copilot extension, so we follow Copilot conventions. This is what
     esolveSkillPath(), squad build, and our migration tooling use.
   • .squad/skills/ (11 skills) = team-discovered patterns. These are skills agents discovered during work (economy mode, session recovery, etc.). Our coordinator prompt tells agents to check both, because teams often find improvements we didn't anticipate.

   Why not .github/skills?

   That comment in #354 was about different platforms—Claude Code uses .claude/skills, some setups use .github/skills. Squad uses .copilot/skills/ because it's a GitHub Copilot extension, not a Claude extension.

   On the duplication issue

   You're right that this can be confusing, @jackusm. The "duplication" isn't a bug—the directories serve different purposes. But your point about stale references is valid. We do have accumulated opus 4.5 defaults and other LLM-managed state that gets out of sync over time. That's a real issue we're working to clean up (see #624 on template dedup and commit 9081840 on skill migration).

   The right mechanisms

   The squad_skill tool and SkillRegistry.matchSkills() are the proper way to read/write skills and do smart matching. If you're seeing skills not load correctly, those are the places to investigate.

   ---

   This feedback is exactly what makes the project better. We've been actively maintaining this in the current release cycle—keep calling out what feels unclear or broken. 🙏
3. bradygaster commented on Mar 26, 2026

   

   bradygaster

   on Mar 26, 2026

   Collaborator

   More actions

   Thanks for raising this, @sturlath! Both directories are correct by design: .copilot/skills/ contains Copilot CLI process skills, while .squad/skills/ contains Squad team patterns. They serve different purposes in the framework. Appreciate the question! 🙏
4. bradygaster

   closed this as completedon Mar 26, 2026