Skillfold

Declarative skill manager for Claude Code and Codex

Website · Blog · Getting Started · Manifest · CLI

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, install them reproducibly.

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

$ skillfold install
  + commit-helper            ./skills/commit-helper
  + frontend-design          github:anthropics/skills/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.

Get started

npm install -g skillfold       # or: npx skillfold

skillfold init                 # scaffold a manifest and an example skill
skillfold add github:anthropics/skills/skills/frontend-design
skillfold install              # install skills, write the lockfile

Full walkthrough in Getting Started.

How it works

flowchart LR
  L["./skills/local"] --> M
  G["github:owner/repo"] --> M
  N["npm:package/skill"] --> M
  M["skillfold.yaml<br/>what you want"] --> K["skillfold.lock<br/>exact SHA + sha256"]
  K --> I(["skillfold install"])
  I -->|"target: claude"| C[".claude/skills"]
  I -->|"target: codex"| X[".agents/skills"]

Skills come from local directories, GitHub, or npm. The manifest says what you want; the lockfile records exactly what you got. Installs read both.

Reproducible. The lockfile pins the commit SHA or version every remote skill resolved to, plus a sha256 of its contents. skillfold install never moves a pin - only skillfold update does. skillfold install --frozen is npm ci for skills: it fails on any drift and verifies every hash.

Safe by default. Skillfold only writes or prunes directories named in the lockfile. Hand-authored skills sitting next to managed ones are never touched.

Portable. One manifest can install for more than one agent:

targets: [claude, codex]

Skills are plain SKILL.md directories (the agent skills standard), so supporting another tool is just another install location. With codex, skills also land in .agents/skills, and rules sync into a marker-fenced managed block in AGENTS.md that leaves your hand-written content alone.

Verify it in CI

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

skillfold check verifies offline that the manifest, the lockfile, and what is actually installed all agree. It catches the case where someone edits a skill in place and forgets.

Compose skills together

Composed skills concatenate other skills into one generated SKILL.md, regenerated whenever an input changes:

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

Supporting files come along, allowed-tools unions across the inputs, and cycles are rejected at parse time. See Composition.

Manage rules too

The same manifest handles rules - single markdown files installed into .claude/rules/:

rules:
  code-style: ./rules/code-style.md
  security: github:acme/standards/rules/security.md@v3

Rules pin in the lockfile and take part in install, check, list, and remove exactly like skills.

Commands

Add -g to manage your user-level config instead of the current project. See Global vs project and the full CLI reference.

Share your skills

Publish a collection as an npm package with an agentskills map, and anyone can skillfold add npm:my-skills/tdd:

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

The skillfold-skill keyword makes it discoverable through skillfold search. See Publishing.

Skillfold ships its own library of general-purpose skills, each installable with skillfold add npm:skillfold/<name>:

planning · research · decision-making · code-writing · code-review · testing · writing · summarization · github-workflow · file-management · skillfold-cli

Programmatic API

Everything the CLI does is available as a library:

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

License

MIT