Skip to content
Back to search

skills-manager

Manage your agent skills from the conversation: one npx command installs the manager skill, and from then on you just ask your agent — install, import, distribute, update, backfill provenance. Works…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shenysun--skills-manager/badge.svg)](/listings/shenysun--skills-manager)

HTML

<a href="/listings/shenysun--skills-manager"><img src="/api/listings/shenysun--skills-manager/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills-manager-cli

That is the whole setup. Bootstrap creates the skill hub (`~/.skills-manager`), installs the **manager skill** into it from the bundled copy, and mounts it (symlink) into the agents it detects on your machine — you confirm the list in the one prompt it shows.

Then go back to your agent and say:

> **Take stock of my skills: what I have, which agents they are wired into, and what has updates**

**Already have skills in `~/.claude/skills` or other agent runtimes?** Don't migrate during setup — just ask your agent:

> Import my existing skills into skills-manager and tidy up their sources

Content moves into the hub, originals become symlinks (backed up first). Prefer to preview it yourself first? `skills-manager init --dry-run`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 260 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Skills Manager
  2. [![npm](https://img.shields.io/npm/v/skills-manager-cli?color=cb3837)](https://www.npmjs.com/package/skills-manager-cli)
  3. [![npm downloads](https://img.shields.io/npm/dm/skills-manager-cli)](https://www.npmjs.com/package/skills-manager-cli)
  4. [![GitHub stars](https://img.shields.io/github/stars/shenysun/skills-manager?style=social)](https://github.com/shenysun/skills-manager/stargazers)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. [![Node.js](https://img.shields.io/node/v/skills-manager-cli)](https://nodejs.org)
  7. **English** | [简体中文](README.zh-CN.md)
  8. Manage your agent skills **from the conversation**: one `npx` command installs the manager skill, and from then on you just ask your agent — install, import, distribute, update, backfill provenance. Works with any skill-loading agent (Claude Code, Codex, Cursor, …).
  9. > **CLI-first, conversation-driven.** This is `skills-manager-cli` — a terminal/npm tool with an optional local web dashboard. It is not a desktop app; if you were looking for the desktop application of the same name, that is a different project ([xingkongliang/skills-manager](https://github.com/xingkongliang/skills-manager)).
  10. **What makes it different:**
  11. - **One hub, every agent** — a single content library (`~/.skills-manager`) distributes any subset to any of the 70+ catalog agents, symlink or copy per target, with stale-copy detection and rollback.
  12. - **Five source types** — git repos and URLs, direct download URLs (SKILL.md / zip / tar), local zip archives, Claude plugin marketplaces, and well-known discovery indexes.
  13. - **Updates that don't cry wolf** — the update anchor is the git tree SHA of the skill's own subdirectory, so upstream commits outside the skill never light up an update.
  14. - **The resident-cost ledger** — every distributed skill's frontmatter charges each message; `skills-manager cost` accounts it per runtime path (approximate, `≈`) with report-only recall suggestions. Undistributed = zero. See [ADR-0018](docs/adr/0018-resident-cost-ledger.md).
  15. - **Provenance backfill** — imported skills without a source get one through lockfile-evidence adoption, agent-driven search, and your approval.
  16. - **The manager skill** — every management action happens in agent conversation ([ADR-0014](docs/adr/0014-manager-skill-first-bootstrap.md)); the CLI underneath is a plain JSON engine.
  17. - **Skill routing you can CI** — `check` (plus `--overlap` / `--descriptions`), `audit overlap` / `audit descriptions`, and `trigger test "<request>" --expect <skill>` pin which skill a phrasing should pick. Offline, no model. Copy [`examples/github-actions/hub-check.yml`](examples/github-actions/hub-check.yml) + [`trigger-test.yml`](examples/github-actions/trigger-test.yml).
  18. ## Why this instead of `gh skill` / `npx skills` / the desktop app?
  19. | | **skills-manager** | `gh skill` | `npx skills` | [desktop skills-manager](https://github.com/xingkongliang/skills-manager) |
  20. |---|---|---|---|---|
  21. | Primary UI | **Agent conversation** (manager skill) + CLI | GitHub CLI | CLI | Desktop GUI |
  22. | Hub model | Single `~/.skills-manager` → distribute subset | Per-agent / shared `.agents/skills` | Per install | Hub + presets |
  23. | Agents covered | **70+** (catalog snapshot) | ~48 | Depends on target | ~54 |
  24. | Non-GitHub sources | git / URL / zip / marketplace / well-known | GitHub (+ `--from-local`) | GitHub-centric | Marketplace + git |
  25. | Update signal | **Skill subtree tree-SHA** (no false positives) | Frontmatter tree SHA | Lockfile / metadata | App sync |
  26. | Context cost | Built-in **resident cost ledger** | — | — | — |
  27. | Skill quality / routing CI | `check` · `audit overlap/descriptions` · `trigger test --expect` | — | — | — |
  28. | Multi-machine | Hub git sync (`sync push/pull`) | — | — | Device-code backup |
  29. | Install | `npx skills-manager-cli` | `gh extension` | `npx skills` | Desktop download |
  30. Pick this when you want **one library, many agents, conversation-driven ops**, and honest update/cost signals — not another one-shot installer.
  31. ## Quick Start
  32. ```sh
  33. npx skills-manager-cli
  34. ```
  35. ![skills-manager demo](docs/assets/demo.gif)
  36. *`--help` and the resident context-cost ledger (`cost`) in action. After bootstrap, try `cost --share` and `doctor` — both are printed as pasteable demos.*
  37. Skill quality in the terminal (asciinema-style; no GIF required):
  38. ```text
  39. $ skills-manager check --overlap --descriptions
  40. check: PASS (4/4 gates)
  41. $ skills-manager audit overlap
  42. Description overlap (idf-jaccard ≥ 0.3) — 1 pair(s) across 12 skill(s)
  43. 0.41 jest-unit-tests ↔ testing-conventions
  44. shared: jest, unit, test
  45. fix: Draw a boundary in each description…
  46. $ skills-manager trigger test "fill PDF form fields" --expect pdf-forms
  47. Trigger test (idf-jaccard) — request: "fill PDF form fields"
  48. scanned 12 skill(s); showing 12
  49. #1 0.312 pdf-forms
  50. shared: pdf, form, field
  51. expect pdf-forms: PASS — pdf-forms ranked #1 (score 0.312)
  52. ```
  53. That is the whole setup. Bootstrap creates the skill hub (`~/.skills-manager`), installs the **manager skill** into it from the bundled copy, and mounts it (symlink) into the agents it detects on your machine — you confirm the list in the one prompt it shows.
  54. Then go back to your agent and say:
  55. > **Take stock of my skills: what I have, which agents they are wired into, and what has updates**
  56. **Already have skills in `~/.claude/skills` or other agent runtimes?** Don't migrate during setup — just ask your agent:
  57. > Import my existing skills into skills-manager and tidy up their sources
  58. Content moves into the hub, originals become symlinks (backed up first). Prefer to preview it yourself first? `skills-manager init --dry-run`.
  59. ## Coming from `npx skills` or `gh skill`?
  60. You can keep installing with those tools. To consolidate into one hub (tree-SHA updates + the cost ledger) without re-downloading:
  61. ```sh
  62. npx skills-manager-cli # bootstrap the hub + manager skill
  63. skills-manager init --dry-run # preview importing existing runtime skills
  64. # or ask your agent: Import my existing skills into skills-manager
  65. skills-manager cost --share # privacy-safe paste card of your resident skill tax
  66. skills-manager doctor --share # privacy-safe hub health card (counts only)
  67. skills-manager update --check # freshness vs skill subtree tree-SHA (git) — no cry-wolf
  68. skills-manager check --overlap --descriptions # one exit code: security + provenance + description quality
  69. skills-manager audit security --strict # CI gate: fail only on high-severity findings
  70. skills-manager audit overlap # which skills compete for the same request (wrong-skill triggers)
  71. skills-manager audit descriptions # descriptions that will never trigger (no "use when", vague, too long)
  72. skills-manager audit descriptions --fix # proposed rewrites as a diff; --write applies them
  73. skills-manager trigger test "…" # offline: which hub skills would this request match? (--expect for CI)
  74. skills-manager trigger test --fixtures f.yml # many {request,expect,top?} assertions in one CI command
  75. skills-manager sync init --remote <url> # multi-machine hub git sync (unique vs installers)
  76. skills-manager sync status --share # privacy-safe paste card of sync posture
  77. ```
  78. `cost --share` prints a paste-ready card (no absolute paths). Example shape:
  79. ```text
  80. Resident skill tax · char-approx · skills-manager
  81. ≈1.2k tokens / message · 12 skill(s) · 2 path(s)
  82. Paths: user/claude-code+zed · project/cursor
  83. Heaviest: big-skill ≈400 · mid ≈200 · small ≈80
  84. Try: npx skills-manager-cli
  85. Reproduce: skills-manager cost --share
  86. https://github.com/shenysun/skills-manager
  87. ```
  88. **CI / skill quality?** Start with the one-exit-code hub gate, then pin routing:
  89. 1. [`examples/github-actions/hub-check.yml`](examples/github-actions/hub-check.yml) — `check` (security + provenance; add `--budget` / `--freshness` / `--overlap` / `--descriptions` as you like).
  90. 2. [`examples/github-actions/trigger-test.yml`](examples/github-actions/trigger-test.yml) — `trigger test "<request>" --expect <skill>` assertions (edit the sample phrasings for your hub).
  91. 3. Optional: [`audit-security.yml`](examples/github-actions/audit-security.yml) when you want PR Files annotations for highs (`--format github`).
  92. Every gate exits 1 on failure and writes its verdict to stderr, so stdout (text/JSON) stays stable:
  93. | Gate | Command | Fails when | Network |
  94. | --- | --- | --- | --- |
  95. | **Hub (all-in-one)** | `check [--budget] [--freshness] [--overlap] [--descriptions]` | any enabled gate fails (security + provenance always) — copy [`hub-check.yml`](examples/github-actions/hub-check.yml) | only with `--freshness` |
  96. | Overlap | `audit overlap --strict` / `check --overlap` | any two descriptions compete for the same request | no |
  97. | Descriptions | `audit descriptions --strict` / `check --descriptions` | any error-level description lint finding | no |
  98. | **Routing** | `trigger test "<request>" --expect <skill> [--top N]` | expected skill is not #1 (or not in top N) — copy [`trigger-test.yml`](examples/github-actions/trigger-test.yml) | no |
  99. | Security | `audit security --strict` | any high-severity finding | no |
  100. | Provenance | `provenance list --fail-on-imported` | an imported skill has no usable source (can't get updates) | no |
  101. | Resident cost | `cost --budget <tokens>` | total resident tokens exceed the budget | no |
  102. | Freshness | `update --check --fail-on-stale` | any skill is stale, or a check fails | yes (`GH_TOKEN` helps) |
  103. Details: [docs/CLI.md](docs/CLI.md).
  104. Runtime copies become hub-backed; originals are backed up first.
  105. ## How it works
  106. ```text
  107. ~/.skills-manager ← hub: the only content authority
  108. skills/<name>/ · registry.yaml
  109. │
  110. │ distribute (symlink / copy)
  111. ▼
  112. ~/.claude/skills ~/.cursor/skills … ← agent runtime dirs
  113. ▲
  114. │ drives, via `npx skills-manager-cli …`
  115. your agent ⇄ the manager skill
  116. ```
  117. - The **manager skill** is the primary interface ([ADR-0014](docs/adr/0014-manager-skill-first-bootstrap.md)): the npx bootstrap installs it and nothing else; every management action afterwards happens through it, in agent conversation. No agent detected yet? Bootstrap still creates the hub and tells you how to mount later.
  118. - It keeps itself current: every CLI run compares the bundled copy with the hub copy and silently refreshes it — unless you edited the hub copy yourself, in which case it is yours and stays untouched.
  119. - The CLI underneath is a plain engine (JSON output, non-interactive flags) — see the [CLI reference](docs/CLI.md).
  120. ## Category sets: load only what you need
  121. Agents load skills wholesale from their runtime dir — no per-skill switch. Domain categories bring that switch to the hub: tag skills with your own vocabulary (frontend / finance / backend — free-form, no controlled list), then apply a category set so an agent's runtime dir holds **exactly** those domains.
  122. > Tag show-me as frontend, then make claude-code load only the frontend skills
  123. ```sh
  124. skills-manager categories set show-me frontend web # replace the whole tag list
  125. skills-manager categories add show-me frontend # incremental
  126. skills-manager categories list # every tag in the hub + counts
  127. skills-manager categories apply frontend finance -a claude-code # rewrite that runtime dir to exactly the set
  128. skills-manager categories apply --all # dissolve the filter, restore every managed skill
  129. skills-manager categories status # per-path applied set + drift
  130. ```
  131. Apply is an explicit, reversible snapshot: missing skills get distributed, managed skills outside the set (including untagged ones) are removed, the manager skill itself and foreign entries are never touched, and re-running the same apply changes nothing. Later tag edits never auto-push — `categories status` reports the drift and re-running `apply` converges. `distribute rollback --to user` restores the runtime content and the category-set record together. Agents sharing one physical runtime dir (an agent family) necessarily share one set. See [ADR-0015](docs/adr/0015-domain-categories-category-set-loading.md).
  132. ## Skill home layout
  133. A skill home contains:
  134. - `skills/`: canonical skill directories, kept flat as `skills/<skill-name>/SKILL.md`
  135. - `collections/`: generated category symlink trees (browse-only)
  136. - `registry.yaml`: metadata — domain categories, legacy category, tags, consumers, source (repo, subpath, ref, baseline), update policy
  137. - `.skills/`: distribution index (`distributions.jsonl`), activity log, optional agent-catalog override
  138. - `.backups/`: pre-init originals, kept for 30 days
  139. Skill home resolution priority:
  140. 1. `--home <path>`
  141. 2. `SKILL_HOME`
  142. 3. current working directory when it already looks like a skill home
  143. 4. `~/.skills-manager` — created by bootstrap only; other commands point you at it instead of creating it
  144. ## Common commands
  145. ```sh
  146. npx skills-manager-cli # bootstrap (default when no subcommand)
  147. skills-manager bootstrap --agent claude-code # scripted bootstrap / mount later
  148. skills-manager doctor
  149. skills-manager doctor --share # privacy-safe hub health paste card
  150. skills-manager list
  151. skills-manager add owner/repo --all --yes
  152. skills-manager distribute --to user --skill my-skill --agent claude-code
  153. skills-manager update --plan
  154. skills-manager update --check # tree-SHA freshness (git/marketplace)
  155. skills-manager update --skill my-skill
  156. skills-manager init --dry-run # preview runtime-skill import
  157. skills-manager init --prefer claude-code hub # this-run conflict priority
  158. skills-manager init --resolve my-skill=cursor # import with a conflict decision
  159. skills-manager backup list # inspect init backups
  160. skills-manager backup restore my-skill # roll one import back
  161. skills-manager edit my-skill --source-git owner/repo --subpath skills/my-skill
  162. skills-manager provenance list # skills still missing a source
  163. skills-manager provenance list --fail-on-imported # fail (exit 1) when any imported skill still lacks a source
  164. skills-manager provenance adopt # backfill lockfile evidence
  165. skills-manager categories set my-skill frontend # tag with a domain category
  166. skills-manager categories apply frontend -a claude-code # load only that domain
  167. skills-manager categories status # applied sets + drift
  168. skills-manager cost # resident context-cost ledger (report-only recall suggestions)
  169. skills-manager cost --budget 2000 # fail (exit 1) when resident context tax exceeds a token budget
  170. skills-manager sync init --remote <url> # multi-machine hub git sync
  171. skills-manager sync status --share # privacy-safe paste card of sync posture
  172. skills-manager update --check --fail-on-stale # fail (exit 1) when any hub skill is stale vs upstream tree-SHA
  173. skills-manager archive old-skill
  174. ```
  175. Sources: GitHub shorthand (`owner/repo`), Git URLs, GitHub tree URLs, local paths, direct download URLs (single `SKILL.md` / zip / tar), local zip archives, plugin marketplaces (`.claude-plugin/marketplace.json`), and well-known discovery indexes — see the [CLI reference](docs/CLI.md).
  176. ## Optional: global install & dashboard
  177. Prefer typing a bare command? Install globally:
  178. ```sh
  179. npm install -g skills-manager-cli # or pnpm add -g skills-manager-cli
  180. ```
  181. Prefer a visual interface? The local dashboard is an optional alternative to the conversation:
  182. ```sh
  183. skills-manager web # http://127.0.0.1:4777, --no-open to skip the browser
  184. ```
  185. It offers the same library on one page: browse, install, update, and distribute. It never creates the hub — run bootstrap first.
  186. ## Development
  187. ```sh
  188. pnpm install
  189. pnpm run build
  190. pnpm test
  191. ```
  192. ## Documentation
  193. - **[Getting Started](docs/GETTING_STARTED.md)** — First run, importing existing skills, common tasks
  194. - **[CLI Reference](docs/CLI.md)** — Full command reference and advanced usage
  195. - **[Architecture](CONTEXT.md)** — Project structure and design decisions

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.