skillcaddy

Skillcaddy

English · 中文

Local AI skills central library + scoped symlink enablement. One library directory holds every skill source; symlink what you need into a project, the shared user-level Agents directory, or Hermes on demand.

Why Skillcaddy?

If you use Claude Code, Codex, OpenCode, or Pi across multiple projects, you eventually hit one of these:

• The same skill lives in three repos, slightly drifted each time
• A new project means copying skills over and wondering which version is current
• An upstream skill gets updated but your local copy is weeks behind
• A Claude-Code-only entry needs to coexist with the agents-side list
• An archived skill slips back in because no one gated it

Skillcaddy fixes this with one library directory as the source of truth and explicit project/global/Hermes symlink scopes as the delivery mechanism.

• One source of truth — one library directory aggregates official / github / personal / archived; the bundled skills/ come with the program
• Install-independent library — the library lives at ~/.skillcaddy/library, so reinstalling or upgrading Skillcaddy never touches your skills
• Zero project pollution — enable by symlink into .agents/skills/; never copy
• Project or global scope — project links stay local; global links go only to ~/.agents/skills/
• Independent Hermes scope — official/github/personal skills explicitly link to ~/.hermes/skills/; it ignores HERMES_HOME and never changes project/global scopes
• Multi-Agent by default — one symlink reaches Claude Code, Codex, OpenCode, Pi via their standard paths
• Independent enable / disable — agents-side and Claude-Code-side are tracked separately
• Safe by default — disable only removes the symlink; archived/ requires explicit naming
• Contribute-friendly — new skills land under skills/<name>/ with SKILL.md + agents/openai.yaml and ship with the repo

Whether you're a solo dev with half a dozen repos, a small team standardizing on shared skills, or an author publishing reusable ones — the contract is the same: skills belong to your library, not to any one project.

Installation

npx skillcaddy                 # one-shot run, nothing to install
npm install -g skillcaddy       # persistent global command

Homebrew installs the published npm tarball through Formula/skillcaddy.rb, which lives in the chenweil/tap tap:

brew tap chenweil/tap
brew install chenweil/tap/skillcaddy

Or use the shell installer:

curl -fsSL https://raw.githubusercontent.com/chenweil/skillcaddy/main/scripts/install.sh | bash

Or run it from source:

git clone https://github.com/chenweil/skillcaddy.git
cd skillcaddy
npm install
npm start

Requires Node.js >= 20. The web manager uses the fixed default URL http://127.0.0.1:4173. Fill in the target project path on the page, and enable/disable skills. If that port is temporarily occupied, start with PORT=<other-port> npm start.

Where the library lives

Skillcaddy separates the code root (the program: package.json, server.js, the bundled skills/) from the library root (your skills: official / github / personal / archived, the source registry, and skill metadata).

• A clone keeps the library inside the clone, exactly as before.
• A packaged install (npx, npm i -g, brew) keeps the library in ~/.skillcaddy/library, so reinstalling or upgrading the program never touches your skills.
• SKILLCADDY_ROOT or --root <dir> points Skillcaddy at any other library directory; the same variable is already used by scripts/pull-github.sh.

Both roots are reported by skillcaddy -a, and the library root is printed by the TUI summary.

Bundled spec-pipeline skills

This repository ships three skills under skills/spec-pipeline/ that implement the direction-confirmation gate described in docs/research/0037. They are tracked in git, so a clone has the content — but the project enablement links are not, by design: ADR 0011 Decision 4 keeps project enablements out of the library image (lib/libraryImage.js carries only global and hermes triples). Recreate the links once per checkout:

npm run enable:spec-pipeline
# preview without touching anything
npm run enable:spec-pipeline -- --dry-run

Then check that every spec in this repository satisfies the gate:

npm run check:specs

Both commands are idempotent. check:specs is also part of npm test; a repository with no specs/ directory passes, and --strict inverts that.

The Web library keeps project, global, and Hermes enablement independent. Enabling a skill globally does not disable its project action: you can still add the same skill to the current project when that project needs its own setup, Claude Code synchronization, or explicit project-level precedence. Collection actions show separate project/global/Hermes progress; text search expands matching collections, while source and tag filters keep collections collapsed for compact browsing. The enabled panel presents project Agents and Claude Code as side-by-side channel slots, with full-width global and Hermes slots below; a shared enabled-skill search finds a name or source without scrolling long lists.

Global CLI / TUI command

A packaged install already provides the skillcaddy command. When you work from a clone, link that clone's command globally instead (local npm link):

npm run install:cli
npm run check:cli

The installed skillcaddy command provides both the CLI and TUI. The older install:tui / check:tui names remain as compatibility aliases. You can also run npm run tui -- install cli from the clone, or choose 11. 安装/检查全局 CLI + TUI 命令 inside the TUI.

After linking the local CLI/TUI command once, the same entry point can manage the Web server and inspect or update skills from any project:

skillcaddy start [projectPath]     # start the Web manager
skillcaddy stop                    # stop Skillcaddy-owned Web only
skillcaddy restart [projectPath]   # restart the Web manager
skillcaddy -v                      # show the version
skillcaddy -h                      # show help
skillcaddy -u [projectPath]        # safely update registered Git skill sources
skillcaddy -a [projectPath]        # report project state, advice, and recommendations
skillcaddy enable <skill-id> --project <dir> [--alias <name>]
skillcaddy enable <skill-id> --global [--alias <name>]
skillcaddy enable <skill-id> --hermes [--alias <name>]
skillcaddy disable <alias> --project <dir>
skillcaddy disable <alias> --global
skillcaddy disable <alias> --hermes

-a is read-only and never creates source folders, installs, enables, or writes metadata. -u reuses the existing fast-forward-only Git source update flow and requires an explicit current project path; global links are checked in the same update. start reuses a Web process that is already running; stop and restart act only on a process whose Skillcaddy ownership can be verified, so an external service on the port is not killed. --root selects the library root and applies to every command, including the Web lifecycle; the Web process always runs the code root that provides the executable. Running skillcaddy without arguments still opens the TUI.

On platforms without a process-ownership probe, Web stop/restart fail closed rather than guessing which process to terminate.

If you do not want to link the global command yet, the repository-local entry supports the same commands:

npm run tui -- start --no-open
npm run tui -- stop
npm run tui -- -a /path/to/project

Terminal UI (TUI)

For the interactive terminal manager, run:

npm run tui -- /path/to/project
# or with explicit root
npm run tui -- --root ~/.skillcaddy/library /path/to/project

To use the cloned library from any project, link its CLI/TUI command once:

npm run install:cli
npm run check:cli

cd /path/to/another-project
skillcaddy

install:cli uses local npm link: it links this clone instead of downloading a package. The global skillcaddy command remains linked to this clone, which stays the central library and can be updated with git pull. Running skillcaddy without an argument manages the current directory; skillcaddy /path/to/project selects another project. The installer refuses to replace a global skillcaddy package linked to another clone.

The TUI provides a full keyboard-driven interface without needing a browser:

• View enabled skills — Agents and Claude Code columns side by side
• Browse/search skill library — Keyword search, source filter, library drill-down
• Enable skill — Creates symlink in .agents/skills/ and auto-syncs Claude Code
• Enable globally — Adds an explicit shared link under ~/.agents/skills/ without requiring a project
• Clear enabled skill — Removes project symlink only; source stays safe
• Manage global skills — Option 13 inspects, enables, and safely removes links owned by this central library under ~/.agents/skills/
• Manage Hermes skills — Option 14 explicitly inspects, enables, and safely removes eligible links under ~/.hermes/skills/
• Sync Claude Code — One-click sync .claude/skills/ with .agents/skills/
• Edit metadata — Inline note, tags, auto-enable toggle per skill
• View diagnostics — Advice on duplicates, broken links, source drift
• Track collection setup — Distinguish enabled links from project-ready configuration and guide interactive setup
• Resolve duplicate names — Enable a selected source skill under a suggested or custom project alias without renaming the source
• Refresh project — Reload state, switch project path
• Update GitHub sources — Batch fast-forward pull github/ repos
• Batch Chinese notes — Interactive flow (option 10) to fill missing Chinese note fields for skills that only have an English description
• Install/check the global command — Option 11 installs the CLI + TUI command from this clone
• Acquire remote sources — Option 12 adds complete HTTPS/SSH/SCP Git repositories, public HTTP(S) ZIP files, or stable direct HTTP(S) /SKILL.md files to the central library

Library browsing now shows skills in a compact paginated table (n/p to page through, a to bulk-enable). The skill introduction prefers the metadata note over the raw English description when both exist.

Menu navigation uses number keys (1-14) for actions, /keyword for search, b to go back, q to quit. Ideal for quick terminal workflows or headless environments.

To make the bundled skillcaddy-manager skill available to AI agents from any project, install its global entry once:

npm run install:manager
npm run check:manager

This creates a managed symlink at ~/.agents/skills/skillcaddy-manager pointing back to skills/skillcaddy-manager. It will not overwrite an existing file, directory, or symlink that points somewhere else.

You can also pass the project path through the URL:

http://127.0.0.1:4173/?projectPath=<encoded-project-path>

The page loads that project immediately, keeps recently used project paths in browser-local history, and lets you bulk-enable all available skills from a library with the library-level + button. The enabled panel groups project Agents, Claude Code, global Agents, and Hermes into explicit channel slots and provides one shared search across their enabled entries. If a library was enabled by mistake, use the library-level × button to clean that library from both Agents and Claude Code.

Skill metadata