skills-manager

The local control plane for your AI coding-agent skills. Create, organize, sync, back up, and quality-check SKILL.md skills across every agent you use — from one CLI and one local web UI.

skills-manager on GitHub: udayvarmora07/skills-manager. PyPI badge tracks a future release: skill-control-plane is not on PyPI yet, so install from source or pip install the CI-built wheel/sdist below. Distribution name skill-control-plane (skills-mgr entry point) is reserved for that release.

Why this exists

The Agent Skills format (SKILL.md) is now an open standard supported by Claude Code, Cursor, Gemini CLI, OpenCode, Copilot/VS Code, Goose, Amp, and more. The ecosystem has skill libraries (vercel-labs/agent-skills), installers (skills.sh), and a spec — but nobody owns the management problem:

• The same skill copy-pasted into ~/.claude/skills, ~/.codex/skills, Cursor dirs… edits diverge.
• Vague descriptions cause false activation or misses; oversized bodies eat context.
• No versioning, no safe update/rollback, no backup story, no cross-tool view.

skills-manager fills that gap: one store, every scope, full lifecycle.

Install

Requires Python ≥ 3.10. The runtime is stdlib-only — no dependencies.

PyPI is not published yet (see .github/workflows/release.yml for the controlled Trusted Publishing path). Until the first GitHub Release lands:

pipx install skill-control-plane        # recommended (isolated)
# or
pip install skill-control-plane

Run without installing:

git clone https://github.com/udayvarmora07/skills-manager
cd skills-manager
python3 -m skillsmgr --help

Quickstart

# 1. See everything you have, everywhere
skills-mgr list --scope all

# 2. Create a skill once…
skills-mgr create my-workflow -d "Deploys our staging stack. Use when shipping to staging."

# 3. …sync it to every agent you use
skills-mgr sync my-workflow

# 4. Or manage it visually (localhost only, no build step, works offline)
skills-mgr webui

More:

skills-mgr search "deploy" --scope all   # scored search across agents
skills-mgr tokens --scope all            # context-footprint budgeting
skills-mgr validate --all                # spec lint incl. description/body guidance
skills-mgr export                        # timestamped backup tarball
skills-mgr install vercel-labs/agent-skills --dry-run   # preview remote install

Agent scopes

One command surface, per-agent directories underneath:

list, view, search, doctor, stats accept --scope; sync copies between scopes; tokens/install have their own scope semantics. Agent-scope writes go straight to the agent dir (no DB) — disable renames SKILL.md ⇄ SKILL.md.disabled in place, which Claude Code and Command Code both respect.

Web UI

skills-mgr webui              # http://127.0.0.1:8765, opens browser
skills-mgr webui --no-browser # server only
skills-mgr webui --port 9000  # custom port

Stdlib ThreadingHTTPServer backend + vendored Vue 3 (no npm, no CDN, works offline). Scope switcher, live search, trash with undo, validate/doctor/stats/history, templates, tar export plus tar/ZIP import, sync modal. Binds loopback only — never expose it; there is no auth (see Threat model).

Data model

• Filesystem is the source of truth: <data>/skills/<name>/SKILL.md.
• SQLite is a rebuildable index only (db rebuild / db resync repair any drift; never hand-edit it).
• Data dir: $SKILLS_MANAGER_DATA → $XDG_DATA_HOME → ~/.local/share, then /skills-manager.

CLI reference

37 invocable names: 27 top-level commands + 7 trash/templates/db subcommands + 3 ls/rm/gui aliases. Exit codes: 0 ok · 1 error · 2 usage · 130 interrupt. --json on data commands.

Full surface: docs/03-cli-surface.md.

Contributing

PRs welcome — start with CONTRIBUTING.md. Locked constraints for any change:

1. Filesystem stays the source of truth.
2. SQLite schema unchanged.
3. CLI stays stdlib-only.
4. Web UI: stdlib backend, no build step, no new runtime deps, loopback bind.
5. No new CLI commands or Store methods without maintainer approval — open an issue first.

Security

See SECURITY.md for disclosure policy. Design notes: security_best_practices_report.md, skills-manager-threat-model.md.

Roadmap

Where this is going: ROADMAP.md (spec-lint+, cross-scope dedup, registry bridge, eval harness, VS Code extension…).

License

MIT — see LICENSE.