Repository navigation
feat(skills): a user-level default directory, with precedence and provenance - #79
Merged
Merged
Conversation
…venance The loader only ever searched `--skills` directories and the project's `./skills`, so a procedure was per-repo or nowhere: there was no place to keep one for the machine. This adds the level the archetype catalogue asks for — `$XDG_CONFIG_HOME/agent/skills` (`~/.config/agent/skills`), found with no flag. Order *is* the precedence. The directories are searched highest-first — explicit, then project, then user — and the first definition of a name wins, so a project skill overrides the user's copy instead of the two merging silently; the skipped copy is reported along with the level it lost to. `Skill` now carries the `origin` it was found at, and the prompt groups the listing under "Project skills" / "User skills", so provenance is visible rather than implied — the same reason `PlanStep` exists: a run's history should not have to guess where its instructions came from. `skillDirs` moves out of `src/cli.ts` into `src/skills.ts`, where the convention lives, and takes its `cwd`/`env`/`home` as options so the rule is testable without a process. Nothing is fetched and nothing runs at discovery time; this is the half of the skills gap that needed no trust model (refs #78).
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.
What
The discovery half of the skills gap (refs #78, slice 1): a user-level default
directory, precedence between levels, and provenance in the prompt. No network
and no trust model — that is the supply-chain half, which stays open.
$XDG_CONFIG_HOME/agent/skills(~/.config/agent/skills), pickedup with no flag.
--skills, then the project's./skills, then the user default — and the first definition of a name wins, soa project skill overrides the user's copy rather than merging. The skipped copy
is reported:
duplicate skill "x" — already loaded from user (…); keeping that one.Skill.originrecords the level, andskillsPromptgroups the listing under"Project skills" / "User skills" so provenance is visible rather than implied.
skillDirsmoves fromsrc/cli.tstosrc/skills.ts— where the conventionlives — and takes
cwd/env/homeas options, so the rule is unit-testable.Why
A skill that looks local but is not is a real mismatch: a shared, machine-wide
procedure and a repo's own copy of the same name are different instructions.
docs/archetypes/skills-agent.mdrecorded "user / project / remote" discovery as🟡 with no user level; the user level is now done (remote remains a supply-chain
decision, not something to guess at).
Tests
src/skills.test.ts—userSkillsDir(XDG override, blank/absent fallback),skillDirsorder, existence and dedup, origin recorded with the higher levelwinning a collision, and the prompt grouped by level.
src/cli.e2e.test.ts— the real CLI, spawned withXDG_CONFIG_HOMEat a tempdir, loads the user skill with no flag and marks it user-level in the system
prompt (
runClinow accepts env).Gates
pnpm build/pnpm typecheck/pnpm lintgreen.pnpm test— 341 passed, 5 skipped.pnpm test:coverage— 90.5 / 84.2 / 89.6 / 90.5 (thresholds 87/81/86/87).