跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add genged/capshelf --skill capshelf

技能说明


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:

  1. capshelf get-path <item> for the absolute editable path (fragments return canonical data-repo source files; --output returns generated outputs for inspection only).
  2. Edit with your Edit/Write tools.
  3. capshelf status <item> — should report drifted_local (or source_dirty for fragments).
  4. Decide with the user:
    • capshelf promote <item> -m "why" — push to the data repo. Other projects see update available next 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 recorded sourceCommit; first show capshelf status <item> --diff and get permission before using --yes in 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)

阅读完整来源 ↗