[docs] Update documentation for skill target-aware deployment (v0.8.7)#499
Open
danielmeppiel wants to merge 3 commits intomainfrom
Open
[docs] Update documentation for skill target-aware deployment (v0.8.7)#499danielmeppiel wants to merge 3 commits intomainfrom
danielmeppiel wants to merge 3 commits intomainfrom
Conversation
Skill deployment has always been target-aware, but two documentation
sections hardcoded `.github/skills/` as if it were the only destination.
Update both sections to use `{target}/skills/` notation and add a
concrete `--target cursor` example showing `.cursor/skills/` output,
matching the v0.8.7 fix that made SkillIntegrator respect explicit
--target flags end-to-end.
- guides/dependencies.md: update Skill Integration table and intro
- guides/skills.md: update sub-skill promotion description and example
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
danielmeppiel
added
automation
documentation
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Starlight documentation to reflect v0.8.7 behavior where skill deployment honors explicit --target end-to-end (e.g., cursor/opencode skills deploy under their respective dot-directories instead of defaulting to .github/).
Changes:
- Update skills promotion docs to describe target-aware deployment paths and add a
--target cursorexample output. - Update dependency install docs to describe target-specific skills destinations instead of hardcoding
.github/skills/.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/src/content/docs/guides/skills.md | Updates sub-skill promotion narrative and examples to use target-aware paths. |
| docs/src/content/docs/guides/dependencies.md | Updates the "Skill Integration During Install" section to describe target-specific skills directories. |
Comments suppressed due to low confidence (1)
docs/src/content/docs/guides/skills.md:276
- The label "Result after install (default/copilot target)" may be misleading because default installs can be multi-target based on directory auto-detection (e.g., if
.cursor/already exists, skills may deploy there too). Consider clarifying the assumption (e.g., "when only.github/exists" / "when target resolves to copilot") so the example matches the Target Detection behavior described later on the page.
# Result after install (default/copilot target):
.github/skills/
├── my-package/ # Parent skill
│ └── SKILL.md
└── azure-naming/ # Promoted sub-skill
└── SKILL.md
# Result after install (--target cursor):
.cursor/skills/
Comment on lines
+253
to
+257
| On install, APM promotes each sub-skill to a top-level `{target}/skills/` entry alongside the parent — see [Sub-skill Promotion](#sub-skill-promotion) below. | ||
|
|
||
| ### Sub-skill Promotion | ||
|
|
||
| When a package contains sub-skills in `.apm/skills/*/` subdirectories, APM promotes each to a top-level entry under `.github/skills/`. This ensures Copilot can discover them independently, since it only scans direct children of `.github/skills/`. | ||
| When a package contains sub-skills in `.apm/skills/*/` subdirectories, APM promotes each to a top-level entry under `{target}/skills/` (e.g., `.github/skills/`, `.cursor/skills/`, `.opencode/skills/` depending on the active target). This ensures each supported IDE can discover them independently. |
There was a problem hiding this comment.
{target}/skills/ is ambiguous as written because the target name (e.g., cursor) is not the same as the deployed root directory (e.g., .cursor/). Consider renaming the placeholder to something like {target_root_dir} or explicitly listing the supported directories (.github/, .claude/, .cursor/, .opencode/) in the path example so readers don't interpret it as cursor/skills/....
This issue also appears on line 268 of the same file.
See below for a potential fix:
On install, APM promotes each sub-skill to a top-level `{target_root_dir}/skills/` entry alongside the parent - see [Sub-skill Promotion](#sub-skill-promotion) below.
### Sub-skill Promotion
When a package contains sub-skills in `.apm/skills/*/` subdirectories, APM promotes each to a top-level entry under `{target_root_dir}/skills/` (for example `.github/skills/`, `.claude/skills/`, `.cursor/skills/`, `.opencode/skills/` depending on the active target). This ensures each supported IDE can discover them independently.
Comment on lines
+53
to
+57
| Skills are integrated to the target-specific skills directory (e.g., `.github/skills/` for copilot, `.cursor/skills/` for cursor): | ||
|
|
||
| | Source | Result | | ||
| |--------|--------| | ||
| | Package with `SKILL.md` | Skill folder copied to `.github/skills/{folder-name}/` | | ||
| | Package with `SKILL.md` | Skill folder copied to `{target}/skills/{folder-name}/` | |
There was a problem hiding this comment.
This sentence/examples only mention copilot and cursor, but this section is about Claude Skills and APM also supports .claude/skills/ and .opencode/skills/. Consider expanding the examples to include all supported skill targets (or rephrase to avoid implying only those two targets exist).
…31-2509b77fb528110e
…31-2509b77fb528110e
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.
Documentation Updates - 2026-03-31
This PR updates documentation to reflect the v0.8.7 bug fixes that made
SkillIntegratorcorrectly respect explicit--targetflags end-to-end.Features Documented
--target cursordeploys to.cursor/skills/, not.github/skills/(from Does apm support installing skills into Cursor directories? #482, Data-driven integration dispatch: replace if-chain with target × primitive loop #494)--target opencodedeploys to.opencode/skills/, not.github/skills/(from [BUG] --target opencode still writes to .github/prompts/ and .github/agents #488, Data-driven integration dispatch: replace if-chain with target × primitive loop #494)Changes Made
Updated
docs/src/content/docs/guides/dependencies.md: The "Skill Integration During Install" table previously hardcoded.github/skills/{folder-name}/as the deployment destination. Updated the intro sentence and table row to use{target}/skills/{folder-name}/with concrete examples for both copilot and cursor targets.Updated
docs/src/content/docs/guides/skills.md: The "Sub-skill Promotion" section previously described promotion as always going to.github/skills/. Updated the inline reference, the description paragraph, and the code example to reflect target-aware behavior — including a new labeled--target cursorexample showing.cursor/skills/output.Merged PRs Referenced
--target cursorskill deployment fix--target opencodeprimitive dispatch fixNotes
The other v0.8.7 changes (e.g.,
apm deps updateno-op fix, Windows Defender mitigation, sparse checkout per-org token fix) did not require documentation updates — the CLI reference already correctly described the intended behavior, and the fixes align the code to match the docs.