Reconcile agent-skills with both skill hosts - #16
Merged
Conversation
Audited ~/.agents/skills against the upstream agent-skills archive. The skill tables in CLAUDE.md were already exact -- 18 categorised plus 40 workflow skills is precisely the 58 upstream SKILL.md files. Three things did not agree. chezmoi never prunes an archive external, so ~/.agents/skills had 15 entries absent from upstream. Most were inert (no SKILL.md), left by older repo layouts where stripComponents = 2 mapped other top-level dirs into place: agents/scribe -> scribe, .github/workflows -> workflows, benchmarks/suites -> suites. The note on the external blamed upstream skills/ for shipping non-skill dirs; it does not. Two of those 15 were live skills, and one was actively wrong: virtuals-protocol-acp existed in both roots, and the two hosts disagreed about which copy to load. Raxol's Skills.Store scans skills_external_dirs in order and later :ets.insert calls overwrite earlier ones, so its last root (skills-extra) wins. sync-skills.sh links the first root, which was skills/ -- the stale one. After the prettier reformat in #14 the copies diverged, so Claude Code was loading a stale skill while Raxol loaded the current one. Reorder SKILL_ROOTS so both hosts resolve a clash the same way. hf-cli was installed into the external by the hf CLI and tracked by neither repo, so it would vanish on a fresh machine. Vendor it into skills-extra, preserving its empty manifest via the empty_ prefix.
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
1 participant
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.
Audited
~/.agents/skillsagainst the upstreamagent-skillsarchive and againstboth hosts that read it.
What already agreed
The skill tables in
CLAUDE.mdare exact. 18 skills are explicitly categorised(code-pattern, web3, MCP-companion) and the prose claims "Workflow skills (40
total)". Upstream ships 58 directories containing a
SKILL.md, and 58 - 18 = 40.All 18 named skills exist upstream. No change needed.
What did not
1. The external is never pruned.
include = ["*/skills/**"]filters correctlytoday -- a dry-run refresh only wants to add/update real skills. But chezmoi does
not remove entries from an archive external once written, so 15 directories that
no longer exist upstream were still present. Most were inert leftovers from older
repo layouts, where
stripComponents = 2mapped other top-level dirs into place:scribeagents/scribeworkflows.github/workflowssuitesbenchmarks/suiteshooksscripts/hookspg-essayscorpus/pg-essaysThe note on the external blamed upstream
skills/for containing non-skill dirs.It does not -- the archive's
skills/is clean. Note corrected, leftovers removed.2. The two hosts disagreed on a name clash.
virtuals-protocol-acpexisted inboth
skills/(stale) andskills-extra/(chezmoi-managed).Skills.Storescansskills_external_dirsin order and later:ets.insertcalls overwrite earlier ones, so its last root wins ->skills-extra.sync-skills.shlinks the first root, which wasskills/-> the stale copy.This was latent until #14 reformatted
seller.md; the copies then diverged(29237 vs 29292 bytes) and Claude Code was loading a stale skill while Raxol
loaded the current one.
SKILL_ROOTSis now orderedskills-extrathenskills, so both hosts resolve a clash identically.3.
hf-cliwas untracked. Installed into the external by thehfCLI onAug 5, present in neither repo, so it would disappear on a fresh machine. Vendored
into
skills-extra, with its zero-byte manifest preserved via theempty_prefix(chezmoi skips empty files otherwise).
Also documented in
CLAUDE.md: the precedence rule for both hosts, the accountingtable, and one remaining asymmetry -- Raxol globs
**/SKILL.mdat any depth whilethe sync script only looks one level down. Nothing is nested today, so both index
the same 60.
Manual testing
SKILL.md, and both were vendored firstskills-extrahf-clifrontmatter still parses (name,description); prettier's only edits were a blank line and a missing EOF newlinesync-skills.shpasses shellcheck unfilteredpre-commitpasses🤖 Generated with Claude Code