Skillfold

Declarative skill manager for Claude config

Website | Blog | Getting Started | Manifest Reference | CLI Reference

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/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.

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/skills/frontend-design
skillfold list

How it works

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

| Source | Example | | --- | --- | | Local directory | ./skills/commit-helper | | GitHub | github:owner/repo/path/to/[email protected] | | npm | npm:package/[email protected] |

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. Supporting files (references/, scripts/, ...) of the used skills are carried into the composed skill, and its allowed-tools defaults to the union of the used skills' when all of them declare one (override with allowed-tools: on the entry).

Rules

The same manifest also manages 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 participate in install, check, list, and remove exactly like skills.

Codex and other tools

Skills are plain SKILL.md directories (the agent skills standard), so supporting another tool is just more install locations:

targets: [claude, codex]

With the codex target, skills also install into .agents/skills (where Codex looks), and rules sync into a marker-fenced managed block in AGENTS.md - hand-written content around the block is never touched. One manifest, one lockfile, both tools.

Commands

| Command | What it does | | --- | --- | | skillfold init | Scaffold a starter manifest and example skill | | skillfold add <source> | Add a skill to the manifest and install it | | skillfold remove <name> | Remove a skill and uninstall it | | skillfold install | Install every declared skill, write the lockfile | | skillfold install --frozen | Install exactly what the lockfile pins; fail on drift | | skillfold update [name...] | Re-resolve moving refs and reinstall | | skillfold check | Verify manifest, lockfile, and installed skills agree | | skillfold list | Show declared skills and their status | | skillfold info <name> | Show source, pin, hash, and install path for one skill | | skillfold search [query] | Search npm for published skills |

Add -g / --global to any of these to manage your user-level config (~/.claude/skills, and with the codex target ~/.agents/skills + ~/.codex/AGENTS.md) with a manifest at ~/.claude/skillfold.yaml instead of the current project. Project and global levels are independent - the tools themselves layer both at runtime - and check/list warn when a project skill name shadows a user-level one. See Global vs 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

| Skill | Description | | --- | --- | | planning | Break problems into steps, identify dependencies, estimate scope | | research | Gather information, evaluate sources, synthesize findings | | decision-making | Evaluate trade-offs, document options, justify recommendations | | code-writing | Write clean, correct, production-quality code | | code-review | Review code for correctness, clarity, and security | | testing | Write and reason about tests, behavior testing, edge cases | | writing | Produce clear, structured prose and documentation | | summarization | Condense information with audience-appropriate detail | | github-workflow | Work with branches, PRs, issues, and reviews via gh | | file-management | Read, create, edit, and organize files and directories | | skillfold-cli | Use skillfold itself to manage a project's skills |

Programmatic API

Everything the CLI does is available as a library:

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

License

MIT