skillbook

Lock-based skill management for AI coding assistants. Keep a central library and project-local copies that are safe to commit.

How it works

• Library: ~/.skillbook/skills/<id>/ (git repo for versioning)
• Project: <project>/.skillbook/skills/<id>/ (committable)
• Lockfile: skillbook.lock.json stores version + hash per skill
• Harnesses: synced from project skills (.claude/, .codex/, .cursor/, .opencode/, .pi/) using symlink or copy mode

Skills can be single-file (SKILL.md) or multi-file directories (SKILL.md + scripts/references/assets/subfolders).

Install

curl -fsSL https://raw.githubusercontent.com/kurochenko/skillbook/master/install.sh | bash

Quick start

# Initialize library and scan existing projects
skillbook init --library
skillbook scan ~/projects
skillbook list

# Initialize a project and install a skill from the list
cd my-project
skillbook init --project
skillbook install <skill-id>
skillbook harness enable --id opencode --mode symlink

Run from source (dev)

Use this repository version directly with Bun:

bun run dev -- <command> [args]

Example (target a specific project path):

bun run dev -- harness enable --id cursor --mode copy --project "/absolute/path/to/project" --force

Common workflows

1) Build your library (first time)

skillbook init --library
skillbook scan ~/projects

If you already have ~/.skillbook/skills, generate lock entries:

skillbook migrate --library

2) Add a skill from a local file or directory

Import a skill into the library from either a markdown file or a directory containing SKILL.md:

skillbook add ./my-skill.md
skillbook add ./my-skill-dir
skillbook add ./my-skill-dir --name my-skill

For directory skills, skillbook copies the full tree (including nested files).

If you changed a harness skill and want to pull those changes into the project copy first, run:

skillbook harness import --id opencode
skillbook push my-skill

3) Install skills into a project

skillbook init --project
skillbook install my-skill
skillbook install --skills alpha,beta
skillbook harness enable --id cursor --mode copy

4) Update a skill and publish to the library

Edit the project copy (any file in the skill directory), then push:

edit .skillbook/skills/my-skill/SKILL.md
# or edit auxiliary files, e.g.
edit .skillbook/skills/my-skill/scripts/deploy.sh
skillbook push my-skill

5) Pull updates from the library

skillbook pull my-skill
skillbook pull --skills alpha,beta

6) Resolve conflicts

If status shows diverged, pick a winner:

skillbook resolve my-skill --strategy library
# or
skillbook resolve my-skill --strategy project

7) Re-sync harness outputs

If harness files were changed, removed, or drifted:

skillbook harness status --id opencode
skillbook harness sync --id opencode
# overwrite drifted copied harness files
skillbook harness sync --id opencode --force

8) Use copy mode on filesystems without symlink support

If symlinks are unsupported in your environment, use copy mode explicitly:

skillbook harness enable --id opencode --mode copy

When symlink mode is enabled but unsupported by the filesystem, skillbook automatically falls back to copy mode and persists it in skillbook.lock.json.

9) Switch an existing harness from symlink mode to copy mode

Use --force when migrating so existing harness entries are replaced with real files/directories:

skillbook harness enable --id cursor --mode copy --project "/absolute/path/to/project" --force
skillbook harness status --id cursor --project "/absolute/path/to/project"

Repeat for each harness you use: claude-code, codex, cursor, opencode, pi.

10) Operate on multiple skills in one command

The lock workflow commands support --skills (comma-separated):

skillbook install --skills alpha,beta --project /path/to/project
skillbook pull --skills alpha,beta --project /path/to/project
skillbook push --skills alpha,beta --project /path/to/project
skillbook uninstall --skills alpha,beta --project /path/to/project

You can also combine positional + --skills:

skillbook install alpha --skills beta,gamma --project /path/to/project

Common commands

skillbook status                          # project vs library
skillbook add <path> [--name id]          # add from .md file or skill directory
skillbook scan <path>                      # discover skills in existing projects
skillbook diff <id> [--files]              # compare library/project skill content
skillbook install <id> [--skills a,b]     # library -> project
skillbook push <id> [--skills a,b]        # project -> library
skillbook pull <id> [--skills a,b]        # library -> project
skillbook uninstall <id> [--skills a,b]   # remove from project
skillbook resolve <id> --strategy library|project
skillbook harness status --id <harness>
skillbook harness enable --id <harness> --mode symlink|copy

Supported harnesses

Tool	Path	Format
Claude Code	.claude/skills/<id>/SKILL.md	directory
Codex	.codex/skills/<id>/SKILL.md	directory
Cursor	.cursor/rules/<id>.md	file
OpenCode	.opencode/skill/<id>/SKILL.md	directory
Pi	.pi/skills/<id>/SKILL.md	directory

Development

bun run dev -- <command>           # Run CLI in dev mode
bun test                           # Run all tests
bun test src/lib/__tests__/library.test.ts   # Run a single test file
bun test --watch                   # Watch mode
bun run build                      # Compile to dist/skillbook

Test fixtures in test-fixtures/ are generated at runtime and gitignored.

License

MIT