1adf6d2245
* fix(3620): point the docs at files that actually exist docproof found 34 stale references; the reporter hand-read all 34 and reported the 8 that are real, explaining why the other 26 are deliberate (files the documents themselves label legacy or "superseded by", and one pre-Diataxis link label whose target still resolves). Those 26 are left alone — re-touching them would contradict the issue's own analysis. Every claim was re-verified against git ls-files at HEAD before editing. docs/INVENTORY.md said its roster is anchored by six drift-control tests. Five are gone (commands-doc-parity, agents-doc-parity, cli-modules-doc-parity, hooks-doc-parity in 5d8a8c4d; command-count-sync infbf30792), so the sentence now names the one that exists. Whether one test is sufficient coverage is a maintainer question the issue explicitly declined to answer, so no new drift tests are proposed here. The four translations were a revision further behind, each naming a seventh test deleted inae8bb707that the English file had already dropped. All four now match. Renamed targets corrected in CONTEXT.md, VERSIONING.md, docs/CONFIGURATION.md and the update workflow. The new test names carry no issue-NNN- prefix, which is what lint-regression-test-names requires, so they are the correct targets. docs/TESTING-SUITES.md is the one that could cost somebody time: it INSTRUCTED contributors to add an acknowledgment to the legacy drift-ack file, which CONTRIBUTING.md says to never use. Rewritten from the real workflow — per-PR fragments under the drift-acks directory, and a spent base-side ack is re-armed by rewording that fragment's reason in place, never by adding a duplicate, since two sources naming one path is a hard error. docs/skills/discovery-contract.md's heading named a query module deleted in11918dcc. The section was REMOVED rather than retargeted: its documented behavior (skip the deprecated root) is not what the surviving code does — skill-manifest includes that root marked deprecated:true — so retargeting would have documented something false. Found and fixed inline, same class: VERSIONING.md described an SDK bundling step the release workflow does not have (zero such mentions in that file); CONFIGURATION.md and four translations named a dead model-catalog triple collapsed by ADR-457. Dead config removed: the changeset lint's user-facing prefix list still carried two retired sdk entries. git ls-files -- 'sdk/*' returns nothing. No test pins that array. Left deliberately: the comment explaining the retired catalog path, the install regression test that reconstructs the old broken layout to prove it fails, and the generated test-timings cache. Each is a legitimate mention of a dead path, not drift. Note lint-removed-but-needed cannot catch this class: it diffs baseRef...HEAD, so it only sees files deleted in the change under review. These were orphaned by PRs that predate the lint. A repo-wide existence audit would need a suppression mechanism for the 26 deliberate mentions above; that is a feature, not part of this fix. Fixes #3620 * chore(3620): backfill changeset PR number (#3658) --------- Co-authored-by: sim <sim@local>
87 lines
2.4 KiB
Markdown
87 lines
2.4 KiB
Markdown
# Skill Discovery Contract
|
|
|
|
> Canonical rules for scanning, inventorying, and rendering GSD skills.
|
|
|
|
## Root Categories
|
|
|
|
### Project Roots
|
|
|
|
Scan these roots relative to the project root:
|
|
|
|
- `.claude/skills/`
|
|
- `.agents/skills/`
|
|
- `.cursor/skills/`
|
|
- `.github/skills/`
|
|
- `./.codex/skills/`
|
|
|
|
These roots are used for project-specific skills and for the project `CLAUDE.md` skills section.
|
|
|
|
### Managed Global Roots
|
|
|
|
Scan these roots relative to the user home directory:
|
|
|
|
- `~/.claude/skills/`
|
|
- `~/.codex/skills/`
|
|
|
|
These roots are used for managed runtime installs and inventory reporting.
|
|
|
|
### Deprecated Import-Only Root
|
|
|
|
- `~/.claude/gsd-core/skills/`
|
|
|
|
This root is kept for legacy migration only. Inventory code may report it, but new installs should not write here.
|
|
|
|
### Legacy Claude Commands
|
|
|
|
- `~/.claude/commands/gsd/`
|
|
|
|
This is not a skills root. Discovery code only checks whether it exists so inventory can report legacy Claude installs.
|
|
|
|
## Normalization Rules
|
|
|
|
- Scan only subdirectories that contain `SKILL.md`.
|
|
- Read `name` and `description` from YAML frontmatter.
|
|
- Use the directory name when `name` is missing.
|
|
- Extract trigger hints from body lines that match `TRIGGER when: ...`.
|
|
- Treat `gsd-*` directories as installed framework skills.
|
|
- Treat `~/.claude/gsd-core/skills/` entries as deprecated/import-only.
|
|
- Treat `~/.claude/commands/gsd/` as legacy command installation metadata, not skills.
|
|
|
|
## Scanner Behavior
|
|
|
|
### `src/profile-output.cts`
|
|
|
|
- Builds the project `CLAUDE.md` skills section.
|
|
- Scans project roots only.
|
|
- Skips `gsd-*` directories so the project section stays focused on user/project skills.
|
|
- Adds `.codex/skills/` to the project discovery set.
|
|
|
|
### `src/init.cts`
|
|
|
|
- Generates the skill inventory object for `skill-manifest`.
|
|
- Reports `skills`, `roots`, `installation`, and `counts`.
|
|
- Marks `gsd_skills_installed` when any discovered skill name starts with `gsd-`.
|
|
- Marks `legacy_claude_commands_installed` when `~/.claude/commands/gsd/` contains `.md` command files.
|
|
|
|
## Inventory Shape
|
|
|
|
`skill-manifest` returns a JSON object with:
|
|
|
|
- `skills`: normalized skill entries
|
|
- `roots`: the canonical roots that were checked
|
|
- `installation`: summary booleans for installed GSD skills and legacy Claude commands
|
|
- `counts`: small inventory counts for downstream consumers
|
|
|
|
Each skill entry includes:
|
|
|
|
- `name`
|
|
- `description`
|
|
- `triggers`
|
|
- `path`
|
|
- `file_path`
|
|
- `root`
|
|
- `scope`
|
|
- `installed`
|
|
- `deprecated`
|
|
|