capshelf
Use the capshelf CLI to manage shared skills, Pi extensions, subagents, settings, and MCP configs across multiple projects from a user-owned data repo.
genged · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add genged/capshelf --skill capshelfAbout this skill
name: capshelf description: Use the capshelf CLI to manage shared skills, Pi extensions, subagents, settings, and MCP configs across multiple projects from a user-owned data repo.
capshelf
This project uses capshelf to track shared coding-agent config (skills, project-local Pi extensions, Claude/Codex subagents, settings fragments, MCP configs) pulled from a data repo. When the user asks to add, remove, discover, edit, or update shared config, use the capshelf CLI. Do not hand-edit .capshelf/capshelf.json or .capshelf/capshelf.lock.json — they are tool-managed.
Run project commands from anywhere inside a capshelf project — the directory containing .capshelf/capshelf.json, or any subdirectory of it (capshelf walks upward to find the root, like git). init acts on the current directory, not a discovered parent.
Use init only for a new project or a fresh clone without
.capshelf/local.json; it refuses a project already initialized on this
machine. Use data bind, data upstream, and update for later lifecycle
changes.
The agent decision loop
Work the shelf in this order instead of pattern-matching on bare item names:
1. Survey the project
Run capshelf status at session start to see drift and available updates before changing anything. capshelf ls --here lists what is already installed (with descriptions and #tags when the data repo declares them).
2. Discover on the shelf
Reach for capshelf search <task words> first — it matches names, tags, descriptions, and item content across the bound data repo plus bundled system items, ranked by relevance:
capshelf search "sql injection"
capshelf search security --json
Zero matches exit 0 — an empty answer is a valid answer, not an error. To browse instead, use capshelf ls --tag <tag> (repeatable, AND) or ls --kind <kind>. Descriptions and tags are the selection signal.
Results with a bundles/ prefix are bundles — curated item sets. Prefer them when setting up a project: capshelf show bundles/<name> to preview members and install state, then capshelf add bundles/<name> to expand. Expansion is traceless (members become ordinary independent items); the bundle field in add --json is the only echo and is what belongs in a commit message.
3. Evaluate before installing
capshelf show <item> prints the full description, requires, conflicts-with, and whether each relation is already installed. Use it before committing to an add. For pi-extensions/*, read all extension source shown before adding: Pi executes it as arbitrary code with full user permissions after project trust.
4. Install
capshelf add <item>. For mcp/* and subagents/*, read the targets: block
add prints and tell the user which runtimes the item covers — see Target
coverage. Repeating add for an installed item is a stable no-op; use the printed status --diff, update, and apply guidance instead of trying to make add reapply it. If the output lists missing required items, install them with the exact capshelf add <ref> commands it prints. If add refuses with exit 3 because of a conflicts-with declaration, that is a curated incompatibility — surface the decision to the user (remove the conflicting item, or fix a stale declaration in the data repo); never work around it. A bundle preflight refusal (exit 3) is the same kind of decision: nothing was installed and the per-member report says why — surface it, don't install members one by one to route around it.
5. Verify
capshelf status --strict — exit 0 means the project has converged on its locks.
6. Edit / promote loop
When the user asks you to improve a shared (data) item:
capshelf get-path <item>for the absolute editable path (fragments return canonical data-repo source files;--outputreturns generated outputs for inspection only).- Edit with your Edit/Write tools.
capshelf status <item>— should reportdrifted_local(orsource_dirtyfor fragments).- Decide with the user:
capshelf promote <item> -m "why"— push to the data repo. Other projects seeupdate availablenext time they check; nothing auto-changes.capshelf keep-local <item> --reason "why"— intentional project-specific divergence for a copy item (skill or Pi extension).capshelf revert <item>— discard the edit, restore from the recordedsourceCommit; first showcapshelf status <item> --diffand get permission before using--yesin a non-interactive run.
For Pi extensions, inspect the changed source before promoting and tell the user to run /reload or restart Pi after materialization. Never imply that capshelf reviewed, trusted, sandboxed, or dependency-installed the extension.
If promote fails with "changed in the data repo since this project last updated" (exit 3), a teammate's newer version is upstream. Show the user the upstream diff (capshelf status <item> --diff plus the scoped git log from the error message). For a skill in either scope or a project-scope Pi extension, offer capshelf promote <item> --merge -m "why" to three-way merge the locked base, installed edits, and current upstream. A merge conflict lists paths and writes nothing. Other choices are preserving the edit and running capshelf update <item> before redoing it, or an intentional overwrite. Do not retry with --stale-ok on your own; --merge and --stale-ok are mutually exclusive. update preflights local drift and asks before replacing installed content; non-interactive and JSON calls refuse unless --yes is passed. Review capshelf status <item> --diff and get the user's permission before using update --yes. For a local-scope item, preserve --local on recovery and merge commands. A merged or ordinary promote that reports already-upstream means the lock was re-pinned without a data-repo commit.
To change metadata (tags, description, requires/conflicts-with, or declared needs)