skilllib 1.0.2 → 1.2.1

package/README.md

@@ -47,6 +47,7 @@ Most agents can't turn off a global skill for just one repo. Claude Code can, bu
 - **📦 Per-repo installs, pinned like dependencies.** Each repo lists its skills and versions in `skilllib.json`. `sync` reproduces them exactly, and `update` moves to the newest.
 - **🤝 One copy, every agent.** skilllib puts one real copy in the repo and links it into whichever folders your other agents read.
 - **🧹 A cleanup wizard for global skills.** For each global skill, pick the repos that should keep it, keep it global, or delete it. Usage numbers and descriptions help you decide.
+- **✓ Global on purpose.** Some skills belong everywhere. Mark them once and skilllib stops warning about them.
 - **🔎 See everything in a repo:**
   - where each skill comes from (the repo, your library, global, a plugin, claude.ai…)
   - which agents load it
@@ -118,8 +119,10 @@ A repo has two lists:
 | Group | What it is | `space` |
 |---|---|---|
 | *From your skills* | Versioned skills you added from your library | Remove it from this repo |
+| *From npx skills* | Skills `npx skills add` installed into this repo (listed in its `skills-lock.json`), with their source | Copy it into your skills; `npx skills` keeps managing this copy |
 | *The repo's own* | Skills committed to the repo (e.g. your team's `.agents/skills`) | Copy it into your skills, so other repos can use it |
-| *⚠ Global · yours* | Your global skills: they load in every repo | Open the cleanup wizard |
+| *⚠ Global · yours, not reviewed* | Your global skills you haven't decided about: they load in every repo | Open the cleanup wizard |
+| *✓ Global · yours, on purpose* | Your global skills you chose to keep global | Open the cleanup wizard |
 | *Global · from vendors* | Plugins, claude.ai skills, Cursor built-ins | – (manage them at the source) |
 
 **Add skills** shows your skills that this repo doesn't have yet. `space` adds one.
@@ -129,11 +132,10 @@ Each row tells you:
 | | Meaning |
 |---|---|
 | **✻ ⬡ ◎ ℤ** | Claude Code, Cursor, Codex, Zed. An icon in color means that agent loads the skill here; a faint one means it doesn't. |
-| `²` | Cursor reaches this skill through two folders, so it may list it twice |
 | `.claude` / `.agents` | The folder holding the real copy |
 | **✓ committed** · **± changed** · **+ not added** · **∅ ignored** | The skill's git state. `∅ ignored` means it only exists on your machine. |
 | `v2` · `v1 → v2` | The installed version, and whether a newer one exists |
-| **⧉ 3 copies** | The same skill reaches your agents from 3 places. The details panel lists them; keep one. |
+| **⧉ 3 copies** | The same skill reaches your agents from 3 places. The details panel lists them, and Health has the fix. |
 | last column | Claude Code uses in the last 30 days |
 
 Related skills fold into one row: skills from the same plugin, the same source repo, or with the same name prefix (`design-*`). Press Enter on the group row for actions on all of them.
@@ -142,7 +144,10 @@ If some skills aren't visible to every agent you use, the top row offers **⇄ M
 
 ### Adding and removing skills
 
-- **Adding** (`space` in *Add skills*) copies the newest version into `.claude/skills/<name>`, which Claude Code and Cursor read. If you use Codex or Zed, it also links it into `.agents/skills`. The skill is recorded in `skilllib.json`. Agents pick it up in their next session.
+- **Adding** (`space` in *Add skills*) copies the newest version into the fewest folders your agents read, and records it in `skilllib.json`. Agents pick it up in their next session. The layout matches `npx skills`' symlink option: the real copy lives in `.agents/skills`, which nearly every agent reads, and Claude Code gets a link.
+  - Claude Code (with or without Cursor): `.claude/skills/<name>`.
+  - Cursor, Codex or Zed without Claude Code: `.agents/skills/<name>`.
+  - Claude Code plus Codex or Zed: the copy goes in `.agents/skills`, with a link in `.claude/skills`. Claude Code only reads `.claude/skills`, and Codex and Zed only read `.agents/skills`.
 - **Removing** (`space` again) deletes that copy and its links. Your library and other repos aren't touched. If you edited it here, skilllib asks first; Enter → *Save local edits to Your skills* keeps them.
 - **The repo's own skills are never deleted by skilllib.** You can copy them into your library, or link them so every agent sees them.
 - **Git-tracked folders:** if the repo commits the folder a link would go into (common for `.agents/skills`), skilllib asks once and remembers your answer.
@@ -171,13 +176,23 @@ Edit a skill once in **Your skills** (Enter → *Edit SKILL.md*). Every repo tha
 Open **Global → ⚠ Clean up…**, or press `space` on any of your global skills. For each skill, `space` cycles through:
 
 - **◉ move:** installed into the repos you tick on the right. Repos that already have it, or where Claude Code used it, are pre-ticked.
-- **○ keep global**
+- **○ keep global**: skilllib remembers this choice, and the next cleanup skips the skill
 - **✕ delete** (`d`): removed without keeping a copy in your library
 
 Each skill shows how often Claude Code used it, and the panel below shows its description and where it was used. Review, apply, and your globals are gone: moved ones are in your library and in the right repos. Originals go to a backup you can restore from **Health**.
 
 You can also delete one skill (Enter → **Delete**) or a whole group (Enter → **Delete all N**) straight from Global.
 
+### Keeping a skill global on purpose
+
+Some skills are useful in every repo, for example a commit-message skill. Mark them so skilllib stops asking about them:
+
+- Enter on the skill (in Global or in a repo) → **✓ Keep global on purpose**. Enter on a group → **Keep all N global on purpose**.
+- In the cleanup wizard, every skill you leave on **○ keep global** is marked when you apply.
+- From the command line: `skilllib global keep <name>`.
+
+A marked skill shows **✓ global** instead of **⚠ loaded globally**, and has its own group in a repo. The cleanup wizard hides it (`k` shows it again), and review prompts tell the agent that you chose to keep it global. The mark only records your decision: no files move, and agents load the skill as before. Duplicate warnings (⧉) still show. To undo, use Enter → **Unmark** or `skilllib global unkeep <name>`.
+
 ### Ask an agent to review your skills
 
 Not sure what to keep? **Copy review prompt** puts a ready-to-paste prompt on your clipboard (also saved to `~/.skilllib/review-prompt.md`). For each skill, it includes:
@@ -196,13 +211,33 @@ It's available from:
 - Enter on any skill or group → **Copy review prompt**
 - `p` inside the cleanup wizard
 
+### Duplicates
+
+The same skill often reaches your agents more than once: a copy in `.claude/skills` *and* in `.agents/skills`, a global copy *and* a repo copy, a plugin *and* your skill. skilllib keeps **one real copy per skill, plus only the links your agents need**. Health shows each case, and `skilllib tidy` fixes the folder ones.
+
+| What it finds | What it does |
+|---|---|
+| Identical copies in several folders | Keeps one and turns the others into links. In a repo, it keeps the committed copy. Globally, it keeps the one in `~/.agents/skills`. |
+| Links no agent you use needs | Removes them. It keeps links that `skilllib.json` records, because teammates may use other agents. |
+| **Copies that differ** | Shows which agent runs which copy (e.g. Claude Code and Cursor run `.claude`, Codex runs `.agents`), and lets you pick the one to keep. |
+| A Claude Code plugin with the same skill | Your skill wins. skilllib copies all the plugin's skills into Your skills, then removes the plugin or turns it off (`claude plugin uninstall` / `disable`). If the plugin also brings MCP servers, hooks, agents or commands, turning it off is the default. |
+| A Cursor plugin with the same skill | Reported only. Turn the plugin off in Cursor. |
+| A repo copy of a skill you keep global | The repo copy is the extra one. Claude Code runs the global copy anyway. |
+
+- **It never moves a real copy.** `skilllib.json` is shared, so a move for your agents could break a teammate's.
+- **It never adds links.** That's **⇄ Make all usable** (`skilllib link`).
+- **It asks before changing committed files.** You choose: *tidy, but keep git as it is*, or *tidy everything*. On the command line, pass `--allow-git`.
+- **Cursor lists a skill once** even when it reaches it through several folders (tested September 2026). It lists a plugin's copy and your copy separately.
+
 ### Health and backups
 
-**Health** lists broken links, skills loaded twice, out-of-date repos and repo-only skills, each with a one-key fix. Below them is everything skilllib ever moved out, and `space` puts it back where it came from.
+**Health** lists broken links, duplicates, copies that differ, skills some of your agents can't reach, out-of-date repos and repo-only skills. Each has a one-key fix, or a short list of fixes to pick from. Below them is everything skilllib ever moved out, and `space` puts it back where it came from.
 
 skilllib never really deletes anything:
 - removed library skills go to `~/.skilllib/trash`
 - removed global skills go to `~/.skilllib/global-backup`
+- copies replaced by a link go to `~/.skilllib/tidy-backup`
+- removed plugins are listed too; restoring one reinstalls it
 
 ---
 
@@ -274,9 +309,11 @@ skilllib sync [--all]           install exactly the pinned versions
 skilllib outdated [--all]       skills with a newer version
 skilllib update [name...]       move to the newest versions
 skilllib link [--all]           make every skill here usable by all your agents
+skilllib tidy [--all|--global]  one real copy per skill, plus only the links your agents need
 
 skilllib list | show <name>     your library
 skilllib import <dir>...        add skill folders to your library (--global: all your global skills)
+skilllib global [keep|unkeep]   your global skills; mark the ones you keep global on purpose
 skilllib new <name> [desc]      create a skill
 
 skilllib usage [--days N]       which skills Claude Code used
@@ -285,7 +322,7 @@ skilllib restore [name]         put back something skilllib moved out
 skilllib --version
 ```
 
-Flags: `--force` (overwrite local edits), `--allow-tracked` (link into git-tracked folders), `--days N`.
+Flags: `--force` (overwrite local edits), `--allow-tracked` (link into git-tracked folders), `--days N`. For `tidy`: `--dry-run` (preview), `--allow-git` (also change committed files), `<name> --keep <folder>` (the copy that wins when copies differ).
 
 ## Files
 
@@ -294,22 +331,23 @@ Flags: `--force` (overwrite local edits), `--allow-tracked` (link into git-track
 | `<repo>/skilllib.json` | The repo's skills and pinned versions. **Commit it.** |
 | `~/.skilllib/library/` | Your skills (master copies). Worth putting under git. |
 | `~/.skilllib/store/` | Every version of every skill, immutable |
-| `~/.skilllib/config.json` | Your agents, project folders, hidden projects |
-| `~/.skilllib/trash/`, `global-backup/` | Everything skilllib removed, restorable from Health |
+| `~/.skilllib/config.json` | Your agents, project folders, hidden projects, skills you keep global |
+| `~/.skilllib/trash/`, `global-backup/`, `tidy-backup/` | Everything skilllib removed, restorable from Health |
+| `~/.skilllib/plugin-backup.json` | Plugins skilllib removed, so Health can reinstall them |
 | `~/.skilllib/review-prompt.md` | The last review prompt you copied |
 
 Environment variables: `SKILLLIB_HOME` moves `~/.skilllib`, `$VISUAL` / `$EDITOR` set the editor, and `CLAUDE_CONFIG_DIR` is honored.
 
 ## FAQ
 
-**Does it change my repos?** Only when you tell it to: adding, removing or linking a skill, which updates `skilllib.json`. It asks before writing into a folder git tracks, and it never deletes a repo's own skills.
+**Does it change my repos?** Only when you tell it to: adding, removing, linking or tidying a skill, which updates `skilllib.json`. It asks before linking into a folder git tracks, and before tidy changes a committed file. It never deletes the only copy of a repo's own skill.
 
-**Can I share skills with my team?** Commit `skilllib.json` along with the copies in `.claude/skills`. Or keep your library in a git repo and point `SKILLLIB_HOME` at it.
+**Can I share skills with my team?** Commit `skilllib.json` along with the skill folders (`.agents/skills`, and `.claude/skills` if you use Claude Code). Or keep your library in a git repo and point `SKILLLIB_HOME` at it.
 
 **Why does usage only count Claude Code?** It's the only agent here with local transcripts to read. Cursor doesn't keep them locally, and Codex's format hasn't been tested yet. That's why "unused" is a strong hint, not proof.
 
 **What's not supported yet?**
-- Cursor marketplace plugin skills: Cursor doesn't record which ones are enabled in a file skilllib can read.
+- Turning off Cursor marketplace plugins: skilllib reports ones that duplicate your skills, but Cursor doesn't record which plugins are on in a file skilllib can read.
 - Unloading a `npx skills` skill doesn't update that tool's lock file.
 - Installing new skills straight from GitHub is coming. For now, `skilllib import <folder>` or copy one from a repo.
 
@@ -328,7 +366,7 @@ npm link                                     # use your checkout as `skilllib`
 1. Bump `version` in `package.json` and merge to `main`.
 2. Tag and push:
    ```bash
-   git tag v1.0.2 && git push --tags
+   git tag v1.2.1 && git push --tags
    ```
 
 CI then tests on Linux, macOS and Windows, publishes to npm through [trusted publishing](https://docs.npmjs.com/trusted-publishers) (no token; provenance is automatic), and creates a GitHub release.