cnife-skill-manager 0.5.0

Project-scoped declarative skill manager for agent skills

Skill Manager

Project-scoped declarative skill manager for coding agents that load skills from ./.agents/skills/ (and optionally ~/.agents/skills/).

One source, many projects, slim globals. Each skill lives once in a cached Source. Projects get symlinks (Links), not copies. Keep agent-global skills minimal; declare per project what you actually need.

Compatible with any agent that discovers skill directories containing SKILL.md under those paths (pi is one example).

Project Links live under ./.agents/skills/; user-global Links under ~/.agents/skills/ are managed with the same model via --global (see Global skills).

Features

• Declare and sync project skills — write .skill-manager.json, run skill-manager sync
• Inspect source and link status — skill-manager list (linked / external / broken / unlinked)
• Enable / disable — interactive menus (multi-select) or non-interactive batch enable <repo> <name>... / disable <name>...
• Manage source cache — skill-manager source list|add|remove|update|available-skills
• Global skills - --global flag applies any command to user-global skills (~/.skill-manager.json, ~/.agents/skills/)
• Scripting / CI — root --json on every command (skill-manager --json <cmd> ...)

Install

uv tool install cnife-skill-manager
# or: pipx install cnife-skill-manager

# from source (dev):
uv tool install .
# or run in-place:
uv run skill-manager

Configure

Create ./.skill-manager.json in your project:

{
  "skills": [
    {"name": "read", "repo": "tw93/Waza", "path": "skills/read"},
    {"name": "kami", "repo": "tw93/Kami", "path": "."}
  ]
}

• name: symlink name under ./.agents/skills/ (single path component; duplicates error)
• repo: GitHub owner/repo (both parts must be safe slug components)
• path: skill directory inside the repo (. for repo-root skills; must contain SKILL.md; path traversal is rejected)

Usage

skill-manager sync                     # clone/fetch sources, link declared skills
skill-manager list                     # show sources and skill status
skill-manager enable                   # interactive: pick repo, multi-select skills, then sync
skill-manager enable <repo> <name>...  # non-interactive batch enable (path derived from cache)
skill-manager enable --all ...         # include hidden/internal skills when resolving
skill-manager disable                  # interactive: multi-select enabled skills
skill-manager disable <name>...        # non-interactive batch disable
skill-manager --json sync              # single JSON object on stdout (all commands)

Batch enable / disable

enable and disable accept multiple skills in one invocation:

skill-manager enable tw93/Waza read write kami   # enable several skills from one repo
skill-manager disable read write                 # disable several skills

• enable is atomic: every name is validated first; if any is missing or ambiguous, nothing is applied and all problems are reported at once (exit 1). Already-enabled names are idempotent no-ops. The whole batch syncs once.
• disable is lenient: disabling a name that is not enabled is a no-op, never an error.
• Interactive multi-select: the menus accept several numbers separated by spaces and/or commas (e.g. 1 3 5 or 1,3); a single number still selects one skill. For enable, the repo is picked first, then skills are multi-selected within it.

Global skills

Add --global to any of sync / list / enable / disable to target user-global skills instead of the project. The user's home is treated as a project: declarations live in ~/.skill-manager.json and links land in ~/.agents/skills/. Sources and the cache are shared across scopes.

skill-manager --global sync                  # link globally-declared skills into ~/.agents/skills/
skill-manager --global list                  # show global skills status
skill-manager --global enable <repo> <name>...  # declare globally + sync (batch)
skill-manager --global disable <name>...        # remove global declarations + links (batch)
skill-manager --json --global list           # JSON output composes with --global

Running skill-manager from ~ without --global targets ~/.skill-manager.json too (home is the global project) — intentional, not a collision.

Source repository management

skill-manager source list                    # list registered sources and HEAD status
skill-manager source add <owner/repo>        # add and clone a new source
skill-manager source remove <repo>           # remove source (cache + config)
skill-manager source update [repo]           # update one or all sources
skill-manager source available-skills [repo] # list skills in the cache (no project config)
skill-manager source available-skills --all  # include hidden/internal skills

sync is idempotent and never overwrites an existing non-tool symlink (it skips with a notice). Sources are derived from the declared skills' repo fields.

Cold start (new source, no hand-edited JSON)

skill-manager source add <owner/repo>              # clone + register globally
skill-manager source available-skills <owner/repo> # optional: discover skill names
skill-manager enable <owner/repo> <name>           # declare in project + sync

enable does not clone; introduce sources with source add (or declare in .skill-manager.json and sync).

Source skill discovery

source available-skills and enable share one scanner over the cached Source checkout:

• Default: skip noise directories (node_modules, dist, build, __pycache__), directories whose names start with . (e.g. .git, .archive, .curated), and skills whose frontmatter has metadata.internal: true.
• --all: include those hidden/internal skills. Skill-root truncation still applies: a directory that contains SKILL.md is one skill and is not walked further.
• Declared skill path values (including under .archive/) are unaffected — sync / list still honor project config as written.

Layouts like skills/.curated/... therefore need --all to appear in discovery (stricter default than some installers that whitelist curated paths).

With --json, success is {"ok": true, "data": ...} and failure is {"ok": false, "error": {"code", "message"}} (exit 0 / 1 / 2 for success / business error / usage error). Place --json before the subcommand: skill-manager --json list, not skill-manager list --json.

Paths (XDG)

What	Path
Global config	$XDG_CONFIG_HOME/skill-manager/config.json (default ~/.config/skill-manager/config.json)
Source cache	$XDG_CACHE_HOME/skill-manager/repos/ (default ~/.cache/skill-manager/repos/)
Project skills	./.agents/skills/
Global skills declaration	~/.skill-manager.json
Global skills	~/.agents/skills/

Roadmap

The What — actionable tickets — lives in the issue tracker. This section is the Why: the shape skill-manager is growing toward.

Dual-user design

skill-manager has two users, and every surface must serve both:

• Humans — an interactive CLI, and a project config (.skill-manager.json) simple enough to read and edit by hand.
• Agents — batch-friendly flags and machine-readable output for scripts, CI, and AFK coding agents.

Any source

A Source shouldn't be locked to owner/repo on GitHub. Arbitrary Git URLs and local directories should qualify too. Pinning a Source to a specific commit or tag for reproducibility is a lower-priority future direction.

One model, project and global

Project Links and user-global Links (~/.agents/skills/) share one declaration-and-sync model via the --global flag: keep globals slim, declare per project what you actually need.