Your .claude/skills directory is state with no source of truth. Skills get pasted in from blog posts, copied between machines, edited in place, and lost on the next laptop. Nobody knows which version of a skill a teammate is running, and "works on my machine" now applies to your agent.

Skillfold treats skills like dependencies. Declare them in one YAML file, pin exact revisions in a lockfile, and install them reproducibly - like nix for skills, without the learning curve.

# skillfold.yaml
skills:
  commit-helper: ./skills/commit-helper
  frontend-design: github:anthropics/skills/frontend-design
  planning: npm:skillfold/planning

$ skillfold install
  + commit-helper            ./skills/commit-helper
  + frontend-design          github:anthropics/skills/frontend-design -> 8f3a9c1
  + planning                 npm:skillfold/planning -> 2.0.0

3 installed, 0 unchanged -> .claude/skills
lockfile: skillfold.lock

Commit skillfold.yaml and skillfold.lock. Anyone who clones the repo runs skillfold install and gets byte-identical skills.

Install

npm install -g skillfold      # or: npx skillfold

Quickstart

skillfold init                # scaffold skillfold.yaml + an example skill
skillfold install             # install into .claude/skills, write skillfold.lock
skillfold add github:anthropics/skills/frontend-design
skillfold list

How it works

Manifest - skillfold.yaml declares skills by name from three kinds of sources:

A trailing @ref pins a version: a tag, branch, or commit SHA for GitHub; an exact version or dist-tag for npm. Unpinned sources resolve to the default branch / latest at install time and are then held by the lockfile.

Lockfile - skillfold.lock records the exact commit SHA or version every remote skill resolved to, plus a sha256 content hash. Installs are reproducible; tampering is detectable. skillfold update is the only thing that moves a pin.

Install - skillfold install materializes every skill into .claude/skills/ (configurable with skillsDir). Skillfold only ever touches directories named in the lockfile - hand-authored skills sitting next to managed ones are never overwritten or pruned.

Check - skillfold check verifies offline that manifest, lockfile, and installed files all agree. Run it in CI:

- uses: byronxlg/skillfold@main   # runs: npx skillfold check

or use skillfold install --frozen for npm-ci-style installs that fail on any drift.

Composition

Composed skills concatenate other skills into one generated SKILL.md:

skills:
  code-review: npm:skillfold/code-review
  testing: npm:skillfold/testing

compose:
  reviewer:
    description: Review code changes together with their tests.
    use: [code-review, testing]

reviewer is generated at install time and regenerated whenever its inputs change. Composed skills can use other composed skills; cycles are rejected at parse time.

Commands

Add -g / --global to any of these to manage ~/.claude/skills (your user-level skills) with a manifest at ~/.claude/skillfold.yaml instead of the current project.

Sharing skills

Publish a skill collection as an npm package with an agentskills map in its package.json:

{
  "name": "my-skills",
  "keywords": ["skillfold-skill"],
  "agentskills": {
    "tdd": "./skills/tdd",
    "docs": "./skills/docs"
  }
}

Anyone can then run skillfold add npm:my-skills/tdd. The skillfold-skill keyword makes the package discoverable via skillfold search. See docs/publishing.md.

Skillfold itself ships a small library of general-purpose skills: planning, research, code-review, testing, writing, and more - skillfold add npm:skillfold/<name>.

Library

Programmatic API

Everything the CLI does is available as a library:

import { loadManifest, resolveManifest, syncSkillsDir } from "skillfold";

License

MIT