docs(skills): document .copilot/skills/ canonical path + .squad/skills/ fallback - #1242
Closed
tamirdresher wants to merge 1 commit into
Closed
docs(skills): document .copilot/skills/ canonical path + .squad/skills/ fallback#1242tamirdresher wants to merge 1 commit into
tamirdresher wants to merge 1 commit into
Conversation
…kills/ fallback
- features/skills.md: skills now live at .copilot/skills/{name}/SKILL.md
(matches squad init, the CLI skill commands, the SDK skill tool, and
the SkillSource fetcher's default)
- Add "Skill directory precedence" section explaining the 5-path read
scan with .squad/skills/ > .copilot/skills/ > .github/skills/ > ...
precedence ordering and dedup rule per .github/agents/squad.agent.md
- Note that .squad/skills/ is still scanned at read time (highest
precedence) for backward compatibility with existing repos
- Update example path: .copilot/skills/ci-github-actions/SKILL.md
- The session-recovery link at line 79 is valid — skill exists at
.squad/skills/session-recovery/SKILL.md (no fix needed)
- concepts/portability.md: update 4 references to .squad/skills/ to
reflect .copilot/skills/ as the canonical write target, keeping
.squad/skills/ noted as legacy fallback where relevant
Closes #1241
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ✅ | Single commit | 1 commit — clean history |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | No source files changed — changeset not required |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | No Copilot review threads |
| ❌ | CI passing | 8 check(s) still running |
Files Changed (2 files, +27 −8)
| File | +/− |
|---|---|
docs/src/content/docs/concepts/portability.md |
+4 −4 |
docs/src/content/docs/features/skills.md |
+23 −4 |
Total: +27 −8
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🟢 Impact Analysis — PR #1242Risk tier: 🟢 LOW 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (2 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Skills documentation to align with the current default write location (.copilot/skills/) while documenting legacy .squad/skills/ support and directory precedence concepts.
Changes:
- Switches canonical documented skill path from
.squad/skills/{name}/SKILL.mdto.copilot/skills/{name}/SKILL.md. - Adds a “Skill directory precedence” section describing multi-directory discovery and conflict resolution.
- Updates portability docs to reference
.copilot/skills/while noting legacy fallback behavior.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/src/content/docs/features/skills.md | Updates canonical skill path and adds a directory precedence section + refreshed examples. |
| docs/src/content/docs/concepts/portability.md | Updates portability references to .copilot/skills/ and mentions legacy fallback. |
|
|
||
| Each skill is a directory containing a `SKILL.md` file. Skills are **team-wide knowledge** — not tied to individual agents. All agents can read and use any skill. | ||
|
|
||
| > **Note:** `.squad/skills/` is a supported legacy path. Skills there are still discovered at read time and take **highest** scan precedence. The CLI, SDK tool, and `squad init` all write to `.copilot/skills/` by default. See [Skill directory precedence](#skill-directory-precedence) below. |
Comment on lines
+41
to
+42
| Squad scans five directories for skills at read time. When the same skill name appears in more than one location, the highest-precedence copy wins: | ||
|
|
Comment on lines
+51
to
+53
| **Writes default to `.copilot/skills/`** — that is what the CLI `skill` commands, the SDK skill tool, sharing/consult, and `squad init` create. `.squad/skills/` is retained for backward compatibility; any skill already there continues to work and takes highest precedence if a same-named skill also exists in `.copilot/skills/`. | ||
|
|
||
| > **Tip:** If you have skills in `.squad/skills/` from an older install, they continue to work as-is. To consolidate, move them to `.copilot/skills/` — but remove the `.squad/skills/` copy first, otherwise the old location will shadow the new one. |
| | Agent histories | ✅ (split into portable vs project-specific) | | ||
| | Casting state | ✅ | | ||
| | Skills | ✅ All earned skills from `.squad/skills/` | | ||
| | Skills | ✅ All earned skills from `.copilot/skills/` (and `.squad/skills/` legacy fallback) | |
| ### What Gets Inherited | ||
|
|
||
| - **Skills** — all `.squad/skills/*/SKILL.md` files | ||
| - **Skills** — all `.copilot/skills/*/SKILL.md` (and `.squad/skills/*/SKILL.md`) files |
Collaborator
Author
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1241
Summary
Resolves the drift between Skills documentation and actual code behavior. The CLI, SDK tool, sharing/consult, and
squad initall use.copilot/skills/as the write target, but the docs still described.squad/skills/as canonical. This PR updates the docs to match the code (Option A from the issue).What changed in the docs
features/skills.md—.squad/skills/{name}/SKILL.md→.copilot/skills/{name}/SKILL.mdas the canonical path, plus a new "Skill directory precedence" section explaining the 5-path scan with.squad/skills/retained as a legacy fallback (still scanned + still wins precedence when both contain a same-named skill).concepts/portability.md— 4 references updated to reflect.copilot/skills/as the write target while noting.squad/skills/as a legacy fallback.session-recoverylink atfeatures/skills.md:79is not broken — the skill file exists at.squad/skills/session-recovery/SKILL.md— so no fix needed.What did NOT change
.squad/skills/is still scanned and still wins precedence at read time. Existing repos with skills there continue to work.listSkillIds()still reference.squad/skills/— flagged in the issue for a future, separate decision.Out of scope
.squad/skills/should eventually be removed entirely (would require migration tooling). That's a separate decision; this PR just stops misleading users.squad.agent.mdskill-aware routing precedence — left to maintainers.skillspath inStatePathMapstill maps to.squad/skills/{id}; that is a separate code-touching change.Test plan
npm run buildpasses locallysession-recoveryskill exists at.squad/skills/session-recovery/SKILL.md(link valid)