skilllib 1.1.0 → 1.2.1

package/README.md

@@ -119,6 +119,7 @@ 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, 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 |
@@ -131,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.
@@ -144,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.
@@ -208,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
 
 ---
 
@@ -286,6 +309,7 @@ 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)
@@ -298,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
 
@@ -308,21 +332,22 @@ Flags: `--force` (overwrite local edits), `--allow-tracked` (link into git-track
 | `~/.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, skills you keep global |
-| `~/.skilllib/trash/`, `global-backup/` | Everything skilllib removed, restorable from Health |
+| `~/.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.
 
@@ -341,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.1.0 && 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.