skill-curator
Curate local Agent Skills libraries: inventory, validate, deduplicate, pin, archive, and restore SKILL.md packages across coding harnesses.
Open source Open in the app JSON README (API)
About
Curate local Agent Skills libraries: inventory, validate, deduplicate, pin, archive, and restore SKILL.md packages across coding harnesses. Use when auditing or maintaining installed skills.
Details
- Kind
- Plugins
- Topic
- E-commerce & business
- Publisher
- cskwork
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Last push
- 2026-08-21T14:49:54Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
cskwork/skill-curator
README
**English** | [한국어](README.ko.md) # skill-curator Agent Skills librarian for LLM coding agents. Use it with Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Antigravity, or any harness that reads `SKILL.md` packages, to inventory what is installed, validate it, find duplicates, and archive dead weight **without losing anything**. **Landing page:** <https://cskwork.github.io/skill-curator/> ## Why This Exists Skill libraries grow faster than anyone curates them. Copies drift across `~/.claude/skills`, `~/.agents/skills`, project checkouts, and harness-specific roots until nobody knows which package actually wins, which one is broken, and which one is a stale twin. `skill-curator` keeps the contract clear: - the engine reports **facts** — discovery, validation, hashes, collisions, lifecycle state - the model makes only **semantic judgments** — is this a true duplicate, a neighbour, or a merge candidate - every package mutation is a **dry run** until you pass `--apply` - nothing is deleted; archives and snapshots keep a full undo route ## Features - Multi-root discovery across Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and custom roots - Frontmatter and package validation with per-skill state: active, stale, unmanaged, pinned, protected, invalid, archived - Exact-duplicate detection by complete-package hash, plus name-collision and precedence reporting - Opt-in lifecycle: newly discovered skills are unmanaged and cannot be pruned until `adopt` - `pin` / `unpin` protection, plus soft protection for Git-tracked project skills - Dry-run-by-default `archive` and `prune`; `--apply` required to move anything - Full-package `archive` → `list-archived` → `restore` round trip, never overwriting an occupied path - `snapshot` / `rollback` with conflict preservation - Symlinked skill entries archived without touching their target - No network access, no telemetry, no invented usage counts ## Install See [INSTALL.md](INSTALL.md) for every harness. Quickest paths: ```bash # Claude Code claude plugin marketplace add cskwork/skill-curator claude plugin install skill-curator@skill-curator # Cursor, OpenCode, Amp, and other agent-skills harnesses npx skills add cskwork/skill-curator # Manual copy into any skills root curl -fsSL https://raw.githubusercontent.com/cskwork/skill-curator/main/install.sh | bash ``` ## Quick Start Ask your agent: ```text Use skill-curator to review all installed coding-agent skills. Show invalid packages, name collisions, exact duplicates, semantic overlap candidates, protected skills, and a dry-run archive plan. Do not mutate anything. ``` Or drive the engine directly: ```bash cd skills/skill-curator python3 scripts/curator.py review --cwd "$PWD" # full inventory report python3 scripts/curator.py validate --cwd "$PWD" # frontmatter and package checks python3 scripts/curator.py duplicates --cwd "$PWD" # exact duplicates and collisions ``` Lifecycle management is opt-in: ```bash python3 scripts/curator.py adopt <skill-id> --cwd "$PWD" python3 scripts/curator.py pin <skill-id> --cwd "$PWD" python3 scripts/curator.py mark-used <skill-id> --cwd "$PWD" python3 scripts/curator.py prune --cwd "$PWD" # dry run python3 scripts/curator.py prune --cwd "$PWD" --apply # archive eligible packages ``` Archive and restore: ```bash python3 scripts/curator.py archive <skill-id> --reason "superseded" --cwd "$PWD" python3 scripts/curator.py archive <skill-id> --reason "superseded" --cwd "$PWD" --apply python3 scripts/curator.py list-archived --cwd "$PWD" python3 scripts/curator.py restore <skill-id> --cwd "$PWD" --apply ``` ## Commands | Command | Purpose | | --- | --- | | `review` | Full inventory with per-skill state and recommendations | | `status` | Compact summary of the current library | | `scan` | Raw discovery across all configured roots | | `validate` | Frontmatter and package structure checks | | `duplicates` | Exact duplicates, name collisions, precedence | | `pin` / `unpin` | Protect a skill from archive and prune | | `adopt` | Opt a skill into age-based lifecycle management | | `mark-used` | Record explicit usage evidence | | `archive` | Move a complete package into the archive (dry run by default) | | `prune` | Archive every eligible adopted skill (dry run by default) | | `list-archived` | List recoverable archived packages | | `restore` | Return an archived package to its original path | | `snapshot` | Copy packages before risky edits | | `rollback` | Restore a snapshot, preserving any changed occupant | ## State Curator-owned state defaults to `~/.skill-curator/`: ```text state.json registry and lifecycle evidence config.json optional custom roots and thresholds archive/<archive-id>/ complete moved packages and manifests backups/<snapshot-id>/ complete copied snapshots and conflicts reports/ optional command reports ``` Set `SKILL_CURATOR_HOME` to relocate it. Add unsupported roots through repeated `--root` flags or `config.json`; see [HARNESS-ROOTS.md](skills/skill-curator/references/HARNESS-ROOTS.md). ## Agent Rule The skill is `disable-model-invocation: true`. The agent must not curate on a hunch — it runs only when you explicitly ask, and it never applies a mutation your request did not authorize. ## Important Limitation This is an on-demand skill, not a background daemon. Coding harnesses do not expose one portable invocation-telemetry API, so the curator does not invent usage counts. It records explicit `mark-used`, first observation, observed content changes, and restores. Harness-specific hooks can call `mark-used` later without changing the archive model. ## Layout ```text skills/skill-curator/ SKILL.md the skill contract scripts/curator.py deterministic engine references/POLICY.md curation policy and safety rules references/HARNESS-ROOTS.md known skill roots per harness agents/openai.yaml OpenAI-style agent metadata tests/test_curator.py isolated test suite docs/index.html landing page (GitHub Pages, EN/KO switchable) install.sh copy the package into a skills root README.ko.md Korean README ``` ## Test ```bash cd skills/skill-curator python3 -m unittest discover -s tests -v ``` The isolated suite covers discovery, validation, duplicate detection, dry-run safety, full-package archive/restore, pinning, adoption-gated pruning, snapshot rollback, Git protection, and symlink handling. ## License MIT — see [LICENSE](LICENSE).