~/project $ skillfold install
One YAML file declares every skill your project uses — local, GitHub, or npm. A lockfile pins exact revisions with content hashes. One command makes .claude/skills match, on any machine. Like nix for skills, without the learning curve.
~/project $ cat skillfold.yaml skills: commit-helper: ./skills/commit-helper code-review: github:anthropics/skills/code-review@v1.2.0 testing: npm:skillfold/testing compose: reviewer: description: Review code changes together with their tests. use: [code-review, testing] ~/project $ skillfold install + commit-helper ./skills/commit-helper + code-review github:anthropics/skills/code-review@v1.2.0 -> 8f3a9c1 + testing npm:skillfold/testing -> 2.0.0 + reviewer composed 4 installed, 0 unchanged -> .claude/skills lockfile: skillfold.lock ~/project $ skillfold check ok: 4 skills in sync
Declare → install → commit the lockfile. Teammates run skillfold install and get byte-identical skills.
Your .claude/skills directory stops being copy-paste state
and becomes a build product: declared, pinned, reproducible.
One manifest maps skill names to sources. Rename, swap, or remove a skill by editing a line, not by shuffling directories.
Every remote skill is pinned to a full commit SHA or exact version, plus a sha256 hash over every file. skillfold.lock is committed; installs repeat byte-for-byte.
Local directories, github:owner/repo/path@ref, or npm:package/skill@version. Paste a GitHub tree URL and it just works.
Composed skills concatenate other skills into one generated SKILL.md — recursive, cycle-checked, regenerated whenever inputs change.
skillfold check verifies manifest, lockfile, and installed files agree — fully offline, nonzero exit for CI. A one-line GitHub Action ships with the repo.
Skillfold only touches directories named in the lockfile. Hand-authored skills sitting next to managed ones are never overwritten or pruned.
A trailing @ref after the last / pins a version:
a tag, branch, or commit SHA on GitHub; an exact version or dist-tag on npm.
Unpinned sources are held steady by the lockfile once resolved.
# skillfold.yaml skills: # local directory, relative to the manifest commit-helper: ./skills/commit-helper # GitHub: owner/repo/path, pinned to a tag code-review: github:anthropics/skills/code-review@v1.2.0 # npm package, agentskills map or subpath testing: npm:skillfold/testing@2.0.0 compose: reviewer: use: [code-review, testing] # optional; default .claude/skills skillsDir: .claude/skills
skillfold install writes skillfold.lock: the full commit SHA
or exact version each skill resolved to, and a sha256 content hash over all of its
files. Installs reuse pins — only skillfold update moves them.
skillfold install --frozen is the CI mode: it fails on any
manifest/lockfile drift and verifies every hash, like npm ci.
Global mode (-g) manages ~/.claude/skills the same way,
so your personal skills follow your dotfiles to every machine.
Everything is also available programmatically:
import { resolveManifest } from "skillfold".
Node 20+. One dependency (a YAML parser). No daemon, no runtime, nothing executes skill content.
npm install -g skillfold
npx skillfold init && npx skillfold install
npx skillfold check
Private GitHub sources use GITHUB_TOKEN. Downloads are cached in ~/.cache/skillfold, keyed by commit SHA / version, so repeat installs are offline.
Any repo with a SKILL.md directory is already a source. For versioned, discoverable
distribution, publish an npm package with an agentskills map and the
skillfold-skill keyword — then anyone can run
skillfold add npm:your-pkg/your-skill.
CI Add uses: byronxlg/skillfold@main to a workflow
(or run npx skillfold check) to fail builds when skillfold.yaml,
skillfold.lock, and .claude/skills disagree. Fully offline; no tokens needed.