Skip to content
Back to search

skillpp

SkillWorks with Claude CodeGitHub

Routing-aware metadata refinement for Claude Code / Agent Skills (unofficial Skill++ implementation)

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/medenor--skillpp/badge.svg)](/listings/medenor--skillpp)

HTML

<a href="/listings/medenor--skillpp"><img src="/api/listings/medenor--skillpp/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.

pipx install "skillpp[llm] @ git+https://github.com/Medenor/skillpp"
# or, in a virtual environment:
pip install "skillpp[llm] @ git+https://github.com/Medenor/skillpp"

export ANTHROPIC_API_KEY=...        # not needed with --offline

The core uses the Python standard library only (Python ≥ 3.10). The `llm` extra installs `anthropic`; the `st` extra installs `sentence-transformers` for dense embeddings.

# 1. Audit: invalid metadata, thin descriptions, duplicated copies
skillpp scan ~/.claude/skills

# 2. Diagnose: which pairs risk substitution, which skills cause crowding
skillpp report ~/.claude/skills

# 3. Preview the refinement of your library, skill by skill (writes nothing)
skillpp insert ~/.claude/skills --profile claude-code --min-sim 0.1 \
    --only 'my-*' --protect 'docx' -v

# 4. Apply once you are happy (originals saved to .skillpp/registry.json)
skillpp insert ~/.claude/skills --profile claude-code --min-sim 0.1 --only 'my-*' --apply

# Undo for one skill
skillpp restore ~/.claude/skills/my-skill/SKILL.md --library ~/.claude/skills --apply

Every command that can write is a **dry run by default**. Add `--offline` to any command to use a deterministic simulated LLM: useful to explore the tool for free, but its rewrites are placeholders, not real descriptions.

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 · 148 lines
  1. # skillpp
  2. [![CI](https://github.com/Medenor/skillpp/actions/workflows/ci.yml/badge.svg)](https://github.com/Medenor/skillpp/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
  5. **Routing-aware metadata refinement for Claude Code / Agent Skills.**
  6. An unofficial, open-source implementation of *Skill++: Towards Lifelong Agents via Routing-Aware Skill Refinement* (Zhang et al., [arXiv:2611.00544](https://arxiv.org/abs/2611.00544)), adapted to `SKILL.md` folders.
  7. > [!IMPORTANT]
  8. > This is **not** the authors' code: none has been published. The prompts in [`src/skillpp/prompts/`](src/skillpp/prompts) are reconstructions from the paper's description, so the paper's numbers do not transfer to this tool. Status: alpha. The pipeline is fully tested offline with a simulated LLM; results with a real LLM still have to be measured on your own library.
  9. ## The problem
  10. An agent's router chooses skills by reading only their `name` and `description`. As a skill library grows, a new skill that resembles an existing one can push it out of the selection, even though neither skill nor the router changed. The paper calls this **routing interference**:
  11. - **substitution**: a similar skill is selected instead of the required one;
  12. - **crowding**: generic or redundant skills take the top-k slots.
  13. Skill++ fixes this at insertion time, without retraining the router and without labelled data: it rewrites **only the name and description of the incoming skill, once**:
  14. 1. **Differentiation**: a short description grounded in the skill's body that stresses what sets it apart from its nearest existing neighbour, without ever naming it.
  15. 2. **Scope exclusions**: synthetic queries locate the 3 existing skills most likely to compete; one short "Does not cover: …" sentence is appended for each.
  16. 3. **Name clarification**: if the new name starts like an existing one (`journaling-*`), a qualifier is appended.
  17. The original metadata is kept in a registry and can be restored at any time.
  18. ## Quick start
  19. ```bash
  20. pipx install "skillpp[llm] @ git+https://github.com/Medenor/skillpp"
  21. # or, in a virtual environment:
  22. pip install "skillpp[llm] @ git+https://github.com/Medenor/skillpp"
  23. export ANTHROPIC_API_KEY=... # not needed with --offline
  24. ```
  25. The core uses the Python standard library only (Python ≥ 3.10). The `llm` extra installs `anthropic`; the `st` extra installs `sentence-transformers` for dense embeddings.
  26. ```bash
  27. # 1. Audit: invalid metadata, thin descriptions, duplicated copies
  28. skillpp scan ~/.claude/skills
  29. # 2. Diagnose: which pairs risk substitution, which skills cause crowding
  30. skillpp report ~/.claude/skills
  31. # 3. Preview the refinement of your library, skill by skill (writes nothing)
  32. skillpp insert ~/.claude/skills --profile claude-code --min-sim 0.1 \
  33. --only 'my-*' --protect 'docx' -v
  34. # 4. Apply once you are happy (originals saved to .skillpp/registry.json)
  35. skillpp insert ~/.claude/skills --profile claude-code --min-sim 0.1 --only 'my-*' --apply
  36. # Undo for one skill
  37. skillpp restore ~/.claude/skills/my-skill/SKILL.md --library ~/.claude/skills --apply
  38. ```
  39. Every command that can write is a **dry run by default**. Add `--offline` to any command to use a deterministic simulated LLM: useful to explore the tool for free, but its rewrites are placeholders, not real descriptions.
  40. ## Commands
  41. | Command | What it does |
  42. |---|---|
  43. | `scan <library>` | Lists every `SKILL.md`, flags missing or overlong fields, `name` ≠ folder, descriptions too thin to route on, duplicated copies. |
  44. | `report <library>` | Closest pairs (substitution risk) and hub skills (crowding risk); duplicated names and diverging copies. |
  45. | `refine <SKILL.md> --library <dir>` | Runs Skill++ on one incoming skill against the whole library. |
  46. | `insert <library>` | **Lifelong mode**, as in the paper: replays the arrival of skills one by one; each is refined once, against the skills inserted before it. |
  47. | `restore <SKILL.md> --library <dir>` | Puts back the original file from the registry. |
  48. | `make-queries <library> --out q.json` | Generates synthetic evaluation queries, including composite ones that need several skills. |
  49. | `evaluate --library <dir> --queries q.json` | Before/after comparison: FC@k, Recall@k, stability (A_old), plasticity (A_new), substitution and crowding errors. |
  50. Run `skillpp <command> --help` for every option.
  51. ## Adapting the paper to Claude Code
  52. The paper evaluates short descriptions against an experimental router. Claude Code allows 1,024 characters and relies on trigger phrases, so `skillpp` adds a few switches. Each one is an extension, not part of the paper:
  53. | Option | Purpose |
  54. |---|---|
  55. | `--profile paper` (default) | 220 characters for the differentiation, 298 in total, as in the paper. |
  56. | `--profile claude-code` | 400 / 800 characters, leaving room for trigger phrases. |
  57. | `--protect PATTERN` or `.skillpp/protect.txt` | Third-party skills (Anthropic, plugins) are never rewritten but still count as neighbours. |
  58. | `--only PATTERN` | Refine only your own skills. |
  59. | `--min-sim X` | Skip skills with no real neighbour, instead of adding unrelated exclusions. `0` reproduces the paper; about `0.1` works with the default TF-IDF embedder. |
  60. | `--keep-crossrefs` | By default, hand-written cross-references such as "Do NOT use for → other-skill" are removed before computing similarities, because they inflate exactly the similarity they try to reduce. |
  61. | `--apply-name` | The clarified name is only written on request: Claude Code expects `name` to match the folder name, so the folder must be renamed by hand. |
  62. Duplicated copies of a skill (for example a synced folder mirroring `~/.claude/skills`) are detected: identical copies are ignored, diverging copies are reported, and a skill is never used as its own neighbour.
  63. ## Evaluating on your own library
  64. Refining descriptions can also hurt routing. Measure before applying at scale: build a query set (`make-queries`, then review it by hand), refine a **copy** of your library with `insert --apply`, and run `evaluate --router llm`. That router reproduces the paper's two-call LLM router (shortlist of 10, then top-k).
  65. The full protocol, metric definitions and caveats are in [docs/evaluation.md](docs/evaluation.md).
  66. ## Documentation
  67. - [docs/method.md](docs/method.md): how each part of the paper maps to the code, and the design choices the paper leaves open.
  68. - [docs/evaluation.md](docs/evaluation.md): evaluation protocol and how to read the metrics.
  69. - [CHANGELOG.md](CHANGELOG.md)
  70. ## Safety guarantees
  71. - No file is modified without `--apply`. A test hashes the whole tree to check it.
  72. - Before the first write, the original file (raw text and SHA-256) is stored in `<library>/.skillpp/registry.json`. It is never overwritten, and later refinements always start from it.
  73. - Writes are atomic. If a `SKILL.md` changes while it is being processed, nothing is written.
  74. - Only the `description` key (and `name`, with `--apply-name`) is rewritten. Other frontmatter keys and the body are preserved byte for byte.
  75. - The API key is read from `ANTHROPIC_API_KEY` and never stored.
  76. ## Limitations
  77. - **Reconstructed prompts.** The exact prompts and the rule that combines the three neighbour scores (σ1–σ3) are not published. This implementation uses Reciprocal Rank Fusion; see [docs/method.md](docs/method.md).
  78. - **Library size.** The paper reports its gains on libraries of 731 skills and more. On a few dozen skills interference is weaker, and so is the expected gain.
  79. - **Default embedder.** A home-made TF-IDF with no dependency, purely lexical. Use `--embedder st` (multilingual sentence-transformers) or plug in your own with `--embedder package.module:Class`.
  80. - **Trigger phrases.** Skill++ replaces the whole description. Trigger lists survive only if the LLM keeps them; check the `-v` output before `--apply`.
  81. - **Languages.** Language detection is a French/English heuristic. Outputs are written in the language of the skill.
  82. - **YAML.** The frontmatter parser handles plain, quoted, `|` and `>` scalars, which is enough for `name` and `description`. Other keys are copied verbatim.
  83. ## Development
  84. ```bash
  85. git clone https://github.com/Medenor/skillpp && cd skillpp
  86. python3 -m venv .venv && source .venv/bin/activate
  87. pip install -e ".[dev]"
  88. pytest # offline, no network
  89. ruff check . && ruff format --check .
  90. ```
  91. See [CONTRIBUTING.md](CONTRIBUTING.md).
  92. ## Citation
  93. If you use this tool, please cite the original paper:
  94. ```bibtex
  95. @misc{zhang2026skillpp,
  96. title = {Skill++: Towards Lifelong Agents via Routing-Aware Skill Refinement},
  97. author = {Zhang, Hanrong and Liang, Minghao and Wu, Jiawei and Chen, Yankai and Fan, Shicheng and Liu, Zhiwei and Ma, Enze and Yuan, Junwei and Wang, Tianyi and Min, Dehai and Zheng, Kening and Liu, Xue and Yu, Philip S.},
  98. year = {2026},
  99. eprint = {2611.00544},
  100. archivePrefix = {arXiv},
  101. primaryClass = {cs.AI}
  102. }
  103. ```
  104. ## License
  105. [MIT](LICENSE). Not affiliated with the authors of the paper or with Anthropic.

Ratings and comments

Sign in to rate this skill.

Sign in

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