mirror of
https://github.com/glittercowboy/get-shit-done
synced 2026-04-25 17:25:23 +02:00
93 lines
2.6 KiB
Markdown
93 lines
2.6 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/get-shit-done/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/get-shit-done/skills/` entries as deprecated/import-only.
|
|
- Treat `~/.claude/commands/gsd/` as legacy command installation metadata, not skills.
|
|
|
|
## Scanner Behavior
|
|
|
|
### `sdk/src/query/skills.ts`
|
|
|
|
- Returns a de-duplicated list of discovered skill names.
|
|
- Scans project roots plus managed global roots.
|
|
- Does not scan the deprecated import-only root.
|
|
|
|
### `get-shit-done/bin/lib/profile-output.cjs`
|
|
|
|
- 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.
|
|
|
|
### `get-shit-done/bin/lib/init.cjs`
|
|
|
|
- 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`
|
|
|