skilllib 1.12.2 → 1.14.0

package/README.md

@@ -9,7 +9,7 @@ and every agent you use can see them.
 [![npm](https://img.shields.io/npm/v/skilllib?color=8b9dff&label=npm)](https://www.npmjs.com/package/skilllib)
 [![license](https://img.shields.io/badge/license-MIT-6bcb77)](LICENSE)
 ![node](https://img.shields.io/badge/node-%E2%89%A522-5eb8f7)
-![agents](https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Cursor%20%C2%B7%20Codex%20%C2%B7%20Zed%20%C2%B7%20Grok-c792ea)
+![agents](https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Cursor%20%C2%B7%20Codex%20%C2%B7%20Copilot%20%C2%B7%20Gemini%20%C2%B7%20OpenCode%20%C2%B7%20Zed%20%C2%B7%20Grok%20%C2%B7%20and%20more-c792ea)
 
 ```bash
 npm install -g skilllib && skilllib agent-skill install
@@ -59,7 +59,7 @@ Most agents can't turn off a global skill for just one repo. Claude Code can, bu
 - **🖥 An app when you want to look yourself.** `skilllib` opens a terminal app with the same data and fixes, and can copy a review prompt for any agent.
 - **🛟 Nothing is lost.** Your library keeps the skills you remove from a repo, and everything else skilllib removes goes to a backup you can restore with one key.
 
-Everything runs locally: no server, no account, no network calls.
+Everything runs locally: no server and no account. `skilllib install` and `skilllib search` are the exception: they talk to [skills.sh](https://skills.sh) and GitHub to fetch a skill.
 
 ---
 
@@ -72,9 +72,10 @@ It needs **Node.js 22+** and works on macOS and Linux. Windows support is newer:
 ```bash
 npm install -g skilllib
 skilllib agent-skill install
+skilllib install anthropics/skills@frontend-design
 ```
 
-This installs the `skilllib` skill where your agents look, in every repo (see [Use it from your agents](#use-it-from-your-agents)). Start a new agent session in any repo and ask away.
+`skilllib agent-skill install` puts the `skilllib` skill where your agents look, in every repo (see [Use it from your agents](#use-it-from-your-agents)). Start a new agent session in any repo and ask away. `skilllib install` puts a skill in your library and, when you run it inside a repo, adds it there so every agent you use can see it. `skilllib search react` finds skills on [skills.sh](https://skills.sh). To load one in every repo, add `--global`.
 
 ### In the app
 
@@ -84,7 +85,7 @@ skilllib    # or: npx skilllib
 
 On first run, skilllib asks two things:
 
-1. **Which agents you use:** Claude Code, Cursor, Codex, Zed, Grok. The ones installed on your machine are pre-selected.
+1. **Which agents you use.** The ones installed on your machine are pre-selected. `skilllib harnesses` lists every one skilllib knows.
 2. **Where your projects live**, e.g. `~/Projects`. It finds every git repo in there, and rescans each time it opens. Agent worktrees (`<repo>/.claude/worktrees/*`) aren't counted as projects.
 
 Then a good first session looks like this:
@@ -97,7 +98,7 @@ Then a good first session looks like this:
 
 ## Use it from your agents
 
-`skilllib agent-skill install` puts a small `skilllib` skill where your agents look: `~/.claude/skills` when one of them reads it (Claude Code, and Cursor and Grok too), and `~/.agents/skills` (a link, or the real copy) for Codex and Zed. This is the one skill that should be global, because it's about every repo. Upgrading skilllib keeps it up to date, and `skilllib agent-skill remove` takes it out. Agents use it from their next session.
+`skilllib agent-skill install` puts a small `skilllib` skill in the global skill folders your agents read: one real copy (usually `~/.claude/skills` or `~/.agents/skills`) and a link in each of the others. This is the one skill that should be global, because it's about every repo. Upgrading skilllib keeps it up to date, and `skilllib agent-skill remove` takes it out. Agents use it from their next session.
 
 Then ask in plain words. A few examples, with what the agent runs:
 
@@ -192,10 +193,10 @@ These are the issues `skilllib doctor` reports, with the same fixes and choices.
 
 A skill's pin goes in one of two places:
 
-- **`skilllib.json` in the repo (shared).** Commit it with the skill folders, and teammates get the same skills. This is where pins go when the repo already has a `skilllib.json`.
-- **Your personal pins (`~/.skilllib/pins/`).** One file per repo, matched by its `origin` remote, so every clone and worktree of the repo shares it. skilllib keeps the copies and links out of git through the repo's `.git/info/exclude` (only your clone; the repo's `.gitignore` doesn't change). Nothing shows up in `git status`. This is where pins go when the repo has no `skilllib.json`.
+- **Your personal pins (`~/.skilllib/pins/`).** The default. One file per repo, matched by its `origin` remote, so every clone and worktree of the repo shares it. skilllib keeps the copies and links out of git through the repo's `.git/info/exclude` (only your clone; the repo's `.gitignore` doesn't change). Nothing shows up in `git status`. A repo that already has `skilllib.json` still gets new skills here.
+- **`skilllib.json` in the repo (shared).** Only when you share a skill with the team: `skilllib add <name> --shared`, or *Pin it for the team* in the app. Commit it with the skill folders, and teammates get that skill.
 
-`skilllib add <name> --personal` or `--shared` picks the place, and moves an existing pin without changing its version. In the app, a library skill's actions offer *Make it personal* or *Pin it for the team*, and its tag says `personal v2`. A copy git already has can't become personal. A skill pinned in both places uses the repo's pin; doctor offers to drop yours (a choice: yours would keep the skill if the team unpinned it).
+`--personal` moves a shared pin back to yours, without changing its version. A copy git already has can't become personal. A skill pinned in both places uses the repo's pin; doctor offers to drop yours (a choice: yours would keep the skill if the team unpinned it). The app tags a personal skill `personal v2`.
 
 **On another machine:** keep `~/.skilllib/pins/` and `~/.skilllib/library/` in git (a dotfiles repo, say). Clone a repo there and run `skilllib sync`: your personal skills come back, out of git again. A repo without a remote keeps its pins by folder, so they stay on that machine until it gets one: adding a remote (or renaming it) keeps them. Only a repo's top folder can have personal pins, not a monorepo package's.
 
@@ -248,7 +249,7 @@ Every plugin issue is *your call*: turning plugins on or off, or updating them,
 
 The details list its skills with their uses, what else it brings, where it's installed and its version. Its actions:
 
-- **Turn it on / off**: `claude plugin enable|disable --scope <scope>`, run in its repo for a project or local install. A plugin synced from claude.ai is switched by its `"<name>@synced"` line in `~/.claude/settings.json`; so is any plugin when the `claude` command isn't available.
+- **Turn it on / off**: `skilllib plugin off <id>` and `skilllib plugin on <id>` (`name@marketplace`). That switches the copy that loads in every repo and leaves a per-repo install on. The same switch is `claude plugin enable|disable --scope <scope>`, run in its repo for a project or local install. A plugin synced from claude.ai is switched by its `"<name>@synced"` line in `~/.claude/settings.json`; so is any plugin when the `claude` command isn't available.
 - **Update to vN**, when its marketplace (as Claude Code last fetched it) declares a newer version or commit: `claude plugin update`. If the marketplace asks to run a command, skilllib doesn't confirm it for you: it tells you to run the update yourself.
 - **Uninstall**: `claude plugin uninstall --keep-data`, where it's installed. Settings › Backups reinstalls it, in the same repo for a project install.
 - **Replace *plugin* with library skills…** copies all its skills into your library (grouped under the plugin), adds them to the repos you tick, and uninstalls the plugin. A plugin can't be half removed, so it's all its skills at once; the confirmation says what else it brings that goes too. If the `claude` command isn't available, skilllib turns the plugin off instead and tells you to finish with `/plugin uninstall`. Plugins synced from claude.ai can't be removed from here: skilllib copies their skills, turns the plugin off, and tells you to remove it on claude.ai.
@@ -384,9 +385,13 @@ Everything the app does also works as a command, for your agents, scripts and CI
 
 ```
 skilllib                        open the app (prints `status` when piped)
+skilllib install <source>...    install from skills.sh, GitHub, or a folder (owner/repo, owner/repo@name, a URL)
+                                 in a repo, also adds them here; --global loads them in every repo; --all installs every skill in a repo
+skilllib search <query>         search skills.sh
+
 skilllib scan [folder...]       add project folders and scan them
 skilllib folders [add|remove]   show or change project folders
-skilllib harnesses [id...]      show or set your agents (claude-code cursor codex zed grok)
+skilllib harnesses [id...]      show or set your agents (skilllib harnesses lists them)
 
 skilllib status                 this repo's skills, which agents load them, and issues
 skilllib add | remove <name>    change this repo's skills
@@ -404,6 +409,8 @@ skilllib new <name> [desc]      create a skill
 
 skilllib projects               your projects and their skills
 skilllib usage [--days N]       which skills Claude Code used (a plugin's copy counts for the skill's name)
+skilllib check [--days N]        what loaded skills cost on every prompt, and which had no use
+skilllib plugin off|on <id>      turn a Claude Code plugin off or on (it stays installed)
 skilllib doctor [--fix]         find (and fix) problems
 skilllib apply <id> [choice]    apply one problem's fix, or the choice you pick (ids from status or doctor --json)
 skilllib restore [name]         put back something skilllib moved out (copies moved together come back together)
@@ -419,7 +426,7 @@ Flags: `--personal` / `--shared` (for `add`: pin in your personal pins or in the
 
 A command exits 1 when it couldn't do all you asked: a skill skipped (not in the library, or local edits in the way), links git-tracked folders blocked, a link something else is in the way of (a file or another copy), an unknown `tidy` name or `--keep` folder, or (with `--all`, and `projects`) a repo left out because its `skilllib.json` can't be read. What it did do is still done, and listed. An unknown or misspelled flag is an error too, so a typo never runs silently. With `--json`, an error that stops a command prints `{"error": "…"}` on stdout as well as the message on stderr. The commands SKILL.md lists as messages-only print nothing on stdout otherwise: read their exit code.
 
-**`--json`** prints one line of JSON on stdout, for scripts and agents. Messages and warnings go to stderr. It works with `status`, `list`, `show`, `projects`, `outdated`, `usage`, `doctor`, `apply`, `add`, `remove`, `sync`, `update`, `import`, `global move` and `agent-skill`. The output is shaped to keep agents fast and cheap:
+**`--json`** prints one line of JSON on stdout, for scripts and agents. Messages and warnings go to stderr. It works with `status`, `list`, `show`, `projects`, `outdated`, `usage`, `doctor`, `apply`, `add`, `remove`, `sync`, `update`, `import`, `global move`, `agent-skill`, `check` and `plugin`. The output is shaped to keep agents fast and cheap:
 
 - **`status --json`** answers everything about the repo in one call:
   - the repo's skills, with their source, version, state and git state
@@ -450,11 +457,13 @@ A field is only removed or changed in a major version.
 
 | Path | What |
 |---|---|
-| `<repo>/skilllib.json` | The repo's shared skills and pinned versions. **Commit it.** |
+| `<repo>/skilllib.json` | Skills you shared with the team (`--shared`). **Commit it** with the skill folders. Absent until then |
 | `~/.skilllib/pins/` | Your personal pins, one file per repo (by its remote). Keep it in git with your library to use them on other machines. |
 | `~/.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/projects.json` | Repos skilllib has seen. Rewritten only when that list changes |
+| `~/.skilllib/usage-cache.json` | Parsed Claude Code transcripts, so the next `status` doesn't read them again. Safe to delete |
 | `~/.skilllib/trash/`, `global-backup/`, `tidy-backup/`, `edit-backup/` | Everything skilllib removed, restorable from Settings › Backups |
 | `~/.skilllib/plugin-backup.json` | Plugins skilllib uninstalled (with their scope and repo), so Settings › Backups can reinstall them |
 | `~/.skilllib/review-prompt.md` | The last review prompt you copied |
@@ -464,11 +473,11 @@ Environment variables: `SKILLLIB_HOME` moves `~/.skilllib`, `$VISUAL` / `$EDITOR
 
 ## FAQ
 
-**Does it change my repos?** Only when you tell it to: adding, removing, linking or tidying a skill, which updates `skilllib.json` (or, for personal pins, your `~/.skilllib/pins/` and the repo's `.git/info/exclude`). 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.
+**Does it change my repos?** Only when you tell it to: adding, removing, linking or tidying a skill. That updates your `~/.skilllib/pins/` and the repo's `.git/info/exclude`, or `skilllib.json` when you share a skill with the team. It asks before linking a shared skill 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 skill folders (`.agents/skills`, and `.claude/skills` if you use Claude Code). Or keep `~/.skilllib/library` in a git repo of its own (the rest of `~/.skilllib` is personal: config, backups, the version store), and run `skilllib import` on teammates' machines from a clone of it.
 
-**Do I have to commit `skilllib.json`?** No. In a repo without one, skilllib pins in your personal pins and keeps its copies out of git, so the repo doesn't change for anyone else. See [Personal or shared pins](#personal-or-shared-pins).
+**Do I have to commit `skilllib.json`?** Only for a skill you shared with the team (`skilllib add <name> --shared`). Everything else stays in your personal pins, out of git. See [Personal or shared pins](#personal-or-shared-pins).
 
 **Why does usage only count Claude Code?** It's the only agent whose transcripts skilllib reads. Grok keeps sessions under `~/.grok/sessions`, and Cursor doesn't keep them locally. Codex's format hasn't been tested yet. That's why "unused" is a strong hint, not proof.
 
@@ -477,7 +486,7 @@ Environment variables: `SKILLLIB_HOME` moves `~/.skilllib`, `$VISUAL` / `$EDITOR
 - Turning off Cursor marketplace plugins: skilllib lists them and reports ones that duplicate your skills, but Cursor doesn't record which plugins are on in a file skilllib can read.
 - Installing plugins from a marketplace: use `/plugin` in Claude Code. Plugins a repo's own `.claude/settings.json` turns on without installing them aren't listed in Plugins yet.
 - Unloading a `npx skills` skill doesn't update that tool's lock file.
-- Downloading skills: skilllib makes no network calls. To get a skill from GitHub, clone the repo and run `skilllib import <folder>`, or ask your agent to.
+- Downloading skills: `skilllib install owner/repo`, `owner/repo@skill`, a skills.sh or GitHub URL, or a local folder. It imports into your library and, in a repo, adds the skill here. `--global` loads it in every repo. `skilllib search <query>` looks up skills.sh. A repo with many skills is listed until you name one or pass `--all`. Everything else skilllib does stays on this machine.
 
 ---