skilllib 1.11.2 → 1.11.4

package/README.md

@@ -45,7 +45,7 @@ Most agents can't turn off a global skill for just one repo. Claude Code can, bu
 
 ## How skilllib fixes it
 
-- **🤖 Your agents run it.** One small skill teaches Claude Code, Cursor, Codex, Zed and Grok to use the skilllib CLI. Ask them what's loaded here, what to add, what's out of date, or to move a global skill into the repos that use it. Every command has `--json` output shaped for agents, and they ask before changing anything.
+- **🤖 Your agents run it.** One small skill teaches Claude Code, Cursor, Codex, Zed and Grok to use the skilllib CLI. Ask them what's loaded here, what to add, what's out of date, or to move a global skill into the repos that use it. The commands agents use have `--json` output shaped for them, and they ask before changing anything.
 - **📚 Your skills: one versioned library.** Every skill has a single master copy in `~/.skilllib/library`, and each change becomes a new version.
 - **📦 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.
@@ -57,7 +57,7 @@ Most agents can't turn off a global skill for just one repo. Claude Code can, bu
   - whether it's committed to git or gitignored
   - how often it was used
 - **🖥 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.** Every removal goes to a backup you can restore with one key.
+- **🛟 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.
 
@@ -90,14 +90,14 @@ On first run, skilllib asks two things:
 Then a good first session looks like this:
 
 1. **You land in Places, on the repo you're in.** `enter` opens its skills; `enter` again opens a skill's issues and actions.
-2. **Open Health** to see everything worth fixing, in every repo and in your global skills. **✦ Fix N issues automatically…** does the safe ones; the rest are your call, one skill at a time.
+2. **Open Health** to see everything worth fixing, in every repo and in your global skills: what `skilllib doctor` reports. **✦ Fix N issues automatically…** does the safe ones; the rest are your call, one at a time.
 3. **Add skills** to a repo with **+ Add a skill…**, the top row of its list.
 
 ---
 
 ## Use it from your agents
 
-`skilllib agent-skill install` puts a small `skilllib` skill in `~/.claude/skills` (Claude Code, Cursor and Grok read it there), with a link in `~/.agents/skills` (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 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.
 
 Then ask in plain words. A few examples, with what the agent runs:
 
@@ -125,8 +125,8 @@ Three panes: **Places** on the left, a **list** on the right, and the **details*
 | **Your skills** | Your library: master copies, versioned. Nothing here loads anywhere until you add it to a repo. |
 | **Global** | Everything your agents load in *every* repo: yours, plus vendor skills (plugins, claude.ai, Cursor built-ins). |
 | **Plugins** | Every plugin installed, on or off: what it brings, where it's installed, and how much its skills get used. Turn it on or off, update it, uninstall it, or replace it with library skills. |
-| **Health** | Every skill with something to fix, in every repo and in Global, with its fixes. |
-| **Projects** | Every repo found in your project folders. `◆` marks the one you're in; `✕` `⚠` `·` its worst issue. |
+| **Health** | What `skilllib doctor` reports, in every repo and in Global, each with its fix or choices. |
+| **Projects** | Every repo found in your project folders. `◆` marks the one you're in; `✕` `⚠` its worst issue. |
 | **Settings** | Your agents and the skilllib skill for them, your project folders, hidden repos, and backups. |
 | **Help** | The keys and symbols. |
 
@@ -137,7 +137,7 @@ Three panes: **Places** on the left, a **list** on the right, and the **details*
 | *type* | Filter the pane you're in. Word initials work too: `cfw` finds `cloudflare-workers`. |
 | `↑` `↓` | Move |
 | `enter` `→` | One pane deeper: Places → list → details. In the details, apply the selected fix or action. |
-| `esc` `←` | One pane back (`esc` clears a filter first). In the details, `←` `→` move along the actions. |
+| `esc` `←` | One pane back (`esc` clears a filter first). In the details, `←` `→` move along a line of actions and `↑` `↓` between lines. |
 | `space` | Apply the ★ recommended fix, or show the choices when it's your call; on a group, open or close it |
 | `tab` | Next tab: All · Issues · Local · Global · Plugins · Vendor |
 | `ctrl+r` | Read everything again from disk · `ctrl+c` quits |
@@ -148,7 +148,7 @@ The list shows everything agents can use in the repo, one row per skill, even wh
 
 | Column | Meaning |
 |---|---|
-| Source | `lib v2`: from your library · `repo`: committed by your team (`.agents/skills` or `.grok/skills`) · `untracked`: only on this machine · `global` (`global ✓`: global on purpose) · `⧉ plugin` · `claude.ai` · `cursor` · `grok` |
+| Source | `lib v2`: from your library · `repo`: the team's (committed to git, or in `.agents/skills` or `.grok/skills`) · `untracked`: only on this machine · `global` (`global ✓`: global on purpose) · `⧉ plugin` · `claude.ai` · `cursor` · `grok` |
 | Uses | Claude Code uses in this repo, last 30 days |
 | Issue | The worst of its issues; the details show them all |
 
@@ -162,15 +162,20 @@ What skilllib flags:
 
 | Issue | Fixes |
 |---|---|
-| **Loaded twice** (also global, or also in a plugin) | Keep the repo's copy and stop loading it globally, or keep it global. Your call: stopping a global skill changes every repo, so the fix names the repos that used it |
-| **Same name as a plugin skill** | Remove the repo's copy, or turn the plugin off in this repo only (`.claude/settings.local.json`, a local-only file git ignores). Cursor ignores repo settings, so once the repo turns the plugin off, only replacing the plugin helps there |
-| **Folder missing** · **Not in your library** | Restore it · copy it back into your library |
-| **Update to vN** · **Edited here** | Update · save the edits as a new version, or discard them |
-| ***Agent* can't see it** | Link it for every agent (links only; nothing is copied or moved) |
-| **Differs from library** · **Not tracked** · **Only in this repo** | Update your library from it, or replace it · track it · import it |
-| **Unused 30 days** | Remove it from the repo |
-| **Broken link** · **Not reviewed** (global) | Remove the link · move it to repos, keep it global on purpose, or delete it |
-| ***Agent* can't see it** (global) | Link it into that agent's global folder, e.g. a Codex skill in `~/.agents/skills` or `~/.codex/skills` gets a link in `~/.claude/skills` |
+| **Repo and global copies** (a repo copy of a skill that also loads globally) | Stop loading it globally. Your call: that changes every repo, so it's offered only when no repo of yours that has or pins the skill would be left with only the global copy for an agent (otherwise the issue says who, and what to do first), and when the global copy is a version in Your skills. If you keep it global on purpose, remove the repo copies skilllib installed instead |
+| **Also in a plugin** | Remove the plugin or turn it off, or turn it off in this repo only (`.claude/settings.local.json`, a local-only file git ignores), or remove your copy from this repo. Cursor ignores repo settings, so once the repo turns the plugin off, only turning the plugin off or removing it helps there |
+| **Folder missing** · **No longer in your library** | Sync the project · copy it back into your library |
+| **Not the pinned version** (the copy is another version from your library, e.g. after a pull) | Install the pinned versions (`sync`; a choice when the copies are committed) |
+| **Out of date** · **Edited here** | Update every out-of-date skill in the repo (or one, from its *Update to vN* action) · save the edits as a new version, or discard them |
+| **Not every agent can use it** | Add the links (links only; nothing is copied or moved). If git tracks a folder a link would go in, you choose whether git sees it |
+| **Differs from your library** · **Not tracked** · **Not in your library** · **From npx skills** | Update your library from it, or replace it with your library's (the team's committed copy is only copied) · track it · import it · import it |
+| **Unused 30 days** | Remove the ones skilllib installed from the repo |
+| **Broken link** (in a repo) | Remove it (your call when git tracks the link). Next to a real copy it's tidy's: it points it at the copy where an agent needs that folder, and removes it otherwise |
+| **Pinned version not in your library** | Install your newest (the folder is missing and your library has no copy of what skilllib.json pins) |
+| **Broken link** · **Not reviewed** (global) | Remove the link · move it to repos, keep it global on purpose, or delete it (the row's actions) |
+| **Not every agent can use it** (global) | Link it into that agent's global folder, e.g. a Codex skill in `~/.agents/skills` or `~/.codex/skills` gets a link in `~/.claude/skills` |
+
+These are the issues `skilllib doctor` reports, with the same fixes and choices.
 
 ### Adding and removing skills
 
@@ -179,9 +184,9 @@ What skilllib flags:
   - Claude Code, with or without Cursor or Grok: `.claude/skills/<name>`.
   - Cursor, Codex, Zed or Grok 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 don't read it.
-- **Remove from repo** deletes that copy and its links; your library keeps it. An untracked copy goes to Settings › Backups instead. If you edited a tracked skill here, skilllib asks first, and the edits go to Settings › Backups.
+- **Remove from repo** deletes that copy and its links; your library keeps it. When the copy itself sits where skilllib doesn't write (a skills folder that links out of the repo, or a file where the copy goes), it drops just the pin and leaves that copy as it is; a link in such a folder is left too, and said. In the app, an untracked copy goes to Settings › Backups instead (`skilllib remove` only removes skills skilllib manages). If you edited a tracked skill here, skilllib asks first, and the edits go to Settings › Backups.
 - **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. If you say no, it tells you which agents can't see the skill there. A skill whose copy git doesn't share (not committed, and not in a folder the repo commits) never gets a link in a committed folder: teammates would get a broken link.
+- **Git-tracked folders:** if the repo commits the folder a link would go into (common for `.agents/skills`), the app asks once and remembers your yes for that repo (in `~/.skilllib/config.json`, `agentsDirOk`); on the command line, `--allow-tracked` allows it for that one command (doctor's *Add links everywhere* choice remembers it, as the app does). If you say no, it tells you which agents can't see the skill there. A skill whose copy git doesn't share (not committed, and not in a folder the repo commits) never gets a link in a committed folder: teammates would get a broken link.
 
 ### Versions
 
@@ -193,7 +198,7 @@ Every change to a library skill becomes a new version, kept in `~/.skilllib/stor
 
 | | Like | What it does |
 |---|---|---|
-| `skilllib sync` | `npm ci` | Installs exactly the pinned versions and restores missing ones. It never touches your edits (`--force` resets them, backing them up first). |
+| `skilllib sync` | `npm ci` | Installs exactly the pinned versions and restores missing ones, with the links skilllib.json records; it never rewrites skilllib.json. It never touches your edits (`--force` resets them, backing them up first). |
 | `skilllib outdated` | `npm outdated` | Lists skills with a newer version |
 | `skilllib update [name]` | `npm update` | Moves to the newest version |
 | *Other versions…* in a skill's actions | `npm i x@1` | Pins any version, including older ones |
@@ -210,7 +215,7 @@ Edit a skill once in **Your skills** (Enter → *Edit SKILL.md*). Every repo tha
 - **Keep it global on purpose**: skilllib stops warning about it (also `skilllib global keep <name>`). The mark only records your decision; to undo it, pick **Stop marking it as global on purpose**.
 - **Delete it**: it goes to Settings › Backups.
 
-When some of your agents can't see a global skill, the flag says so (**Not reviewed · Claude Code can't see it**). This happens, for example, with a Codex skill in `~/.agents/skills` or `~/.codex/skills`, which Claude Code doesn't read. Then a fourth choice appears: **Link it for Claude Code** adds a link in `~/.claude/skills`, and nothing is copied or moved. Moving it to repos works for every agent too. For a skill you keep global on purpose, the link is the ★ fix.
+When some of your agents can't see a global skill, that's a separate issue, **Not every agent can use it**. This happens, for example, with a Codex skill in `~/.agents/skills` or `~/.codex/skills`, which Claude Code doesn't read. Its choice, **Link it for Claude Code**, adds a link in `~/.claude/skills`, and nothing is copied or moved. Moving it to repos works for every agent too. For a skill you keep global on purpose, the link is the ★ fix.
 
 Vendor skills (claude.ai, Cursor built-ins) are managed at their source: claude.ai's settings, or Cursor. A plugin's skills offer **Open *plugin* in Plugins**.
 
@@ -225,8 +230,8 @@ Plugins are a big part of what agents load (one plugin can bring dozens of skill
 | Scope | `user` (every repo) · `project` / `local` and the repo it's installed in · `claude.ai` (synced from your account) |
 | Brings | Its skills, and `+N` for the other kinds of things it brings: commands, agents, hooks, MCP servers |
 | On | `on` · `off` · `?` for Cursor, which keeps that in its own database |
-| Uses | Claude Code uses of its skills (`plugin:skill`), last 30 days. Your own skill by the same name is counted apart; two installs of one plugin share a count |
-| Issue | **Repeats N of yours** (a skill in your library or global folders) · **Unused 30 days** · **Update to vN** |
+| Uses | Claude Code uses of its skills (`plugin:skill`), last 30 days. Your own skill by the same name is counted apart here; `skilllib usage` and `status` count both for the skill's name, so moving a skill out of a plugin keeps its history. Two installs of one plugin share a count |
+| Issue | **Repeats N of yours** (a skill in your library or global folders) · **Unused 30 days** (on, ships skills, none used) · **Update available** (its marketplace has a newer version or commit) |
 
 Every plugin issue is *your call*: turning plugins on or off, or updating them, changes code that runs in your sessions, so **Fix automatically** never does it.
 
@@ -257,26 +262,27 @@ It's in every skill's actions, in a repo's **⋯** menu (all its skills), and at
 
 ### 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** lists each case on the skill it's about, with its fix. From the command line, `skilllib doctor` lists them and `skilllib tidy` fixes the folder ones.
+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** lists each case with its fix, and the skill's row in a repo or Global shows it too. From the command line, `skilllib doctor` lists them 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`. |
+| Identical copies in several folders | Keeps one and turns the others into links where an agent needs that folder (and removes them where none does; a copy the repo commits always stays). 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. It's your call, so **Fix all** never does it. |
-| 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. When the overlap is in one repo, you can instead turn the plugin off only there (in its `.claude/settings.local.json`, which skilllib makes git ignore; without the `claude` command, skilllib writes the file itself), or remove your copy from that repo. If the repo commits its copy, it's the team's: skilllib never offers to remove it. A plugin that a repo's own `.claude/settings.json` turns on counts only in that repo. Cursor ignores repo settings: after a repo turns the plugin off, Cursor still lists both there, and only turning the plugin off or removing it changes that. |
+| Copies that differ behind a link (a link to another copy, in or out of the repo) | Reported only: skilllib never changes what a link points to. Make the copies the same, or remove the link. |
+| 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. When the overlap is in one repo, you can instead turn the plugin off only there (in its `.claude/settings.local.json`: Claude Code makes git ignore it when it writes it; without the `claude` command, skilllib writes the file itself and makes git ignore it), or remove your copy from that repo. If the repo commits its copy, it's the team's: skilllib never offers to remove it. A plugin that a repo's own `.claude/settings.json` turns on counts only in that repo. Cursor ignores repo settings: after a repo turns the plugin off, Cursor still lists both there, and only turning the plugin off or removing it changes that. |
 | 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: remove it, or stop loading the skill globally after all. Claude Code runs the global copy anyway. |
-| A repo's own skill that also loads globally | Stop loading it globally. The repo's copy is the team's, so skilllib never offers to remove it. |
+| A repo's own skill that also loads globally | Stop loading it globally (when no agent in any of your repos would then lack it). The repo's copy is the team's, so skilllib never offers to remove it. |
 
 - **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 `skilllib link`, or a skill's *can't see it* fix.
+- **It never adds links.** That's `skilllib link`, or the *Not every agent can use it* issue's fix.
 - **It leaves committed files alone** unless you say so: Health asks first, and `skilllib tidy` needs `--allow-git`.
 - **Cursor lists a skill once** even when it reaches it through several folders (tested September 2026). It runs the copy from the first of `.cursor`, `.claude`, `.codex`, `.grok`, `.agents` (seen in its app bundle, October 2026). It lists a plugin's copy and your copy separately.
 
 ### Backups
 
-skilllib never really deletes anything you can't get back. What it removes goes to Settings › Backups, and `enter` puts it back where it came from:
+skilllib never really deletes anything you can't get back. What it removes goes to Settings › Backups (`skilllib restore`), and `enter` puts the folder back where it came from. A skill removed from a repo comes back as a folder; doctor then offers to track it again:
 - removed library skills and untracked copies go to `~/.skilllib/trash`
 - removed global skills go to `~/.skilllib/global-backup`
 - copies replaced by a link go to `~/.skilllib/tidy-backup`
@@ -292,7 +298,7 @@ A skill is a folder with a `SKILL.md`. These are all the places your agents load
 | Where | Examples | Who sees it |
 |---|---|---|
 | **The repo** | `.claude/skills`, `.agents/skills`, `.grok/skills`, `.cursor/skills`, `.codex/skills` | Agents working in that repo |
-| **Subfolders** (monorepos) | `packages/web/.claude/skills`, `packages/api/.agents/skills` | Agents working in that folder. `skilllib status` lists them; skilllib never links, tracks or tidies them, since that would make them load repo-wide |
+| **Subfolders** (monorepos) | `packages/web/.claude/skills`, `packages/api/.agents/skills` | Agents working in that folder. `skilllib status` lists them; skilllib never links, tracks or tidies them, since that would make them load repo-wide. A subfolder with its own `skilllib.json` is a project of its own: run skilllib there (scan finds repos, not subfolders). skilllib looks for subfolders up to five folders deep (`apps/web/packages/ui` is four) |
 | **Global folders** | `~/.claude/skills`, `~/.agents/skills` (`npx skills add` installs here), `~/.codex/skills`, `~/.cursor/skills`, `~/.grok/skills` | **Every repo** |
 | **Vendors** | Claude Code plugins (`/plugin`), claude.ai skills, Claude Code's bundled commands, Cursor built-ins and marketplace, Codex system skills and `/etc/codex/skills` (admin), Grok's bundled skills | Every repo (a repo's `.claude/settings.json` can turn a plugin on or off just there); only the vendor can remove them |
 | **Your skills** | `~/.skilllib/library` | Nobody, until you add a skill to a repo |
@@ -356,7 +362,7 @@ A skill is a folder with a `SKILL.md`. These are all the places your agents load
 
   It also reads claude.ai skills under `~/.claude/skills/synced`. It does **not** read `.codex/skills`, and it ignores `CLAUDE_CONFIG_DIR`. Turn a compat folder off with `[compat.claude] skills` or `[compat.cursor] skills` in `~/.grok/config.toml` (`GROK_CLAUDE_SKILLS_ENABLED` / `GROK_CURSOR_SKILLS_ENABLED`). The order above was checked with `grok inspect` on Grok 1.0.41 (October 2026).
 - **How it uses them.** The description decides relevance; `/name` runs one, and Grok can pick one itself. `disable-model-invocation: true` keeps it manual. Project skills in an untrusted folder are skipped.
-- **Installs.** skilllib does not write `.grok/skills` or `~/.grok/skills`. Grok already reads `.agents/skills`, and `.claude/skills` while Claude compatibility is on, so the fewest-folder install reaches it. A skill your team committed in `.grok/skills` stays the repo's own: skilllib can copy it into your library and leaves that folder in place. Adding that library skill back writes a second copy in the usual install folder (`.claude/skills` when Claude Code is enabled, otherwise `.agents/skills`). Grok still runs the team's `.grok/skills` copy. Claude Code runs the library copy. With `[compat.claude] skills = false`, Grok stops reading `.claude/skills`; skilllib still counts that folder as visible to Grok.
+- **Installs.** skilllib does not install into `.grok/skills` or `~/.grok/skills` (the one change it makes there is removing a broken link, when you choose to). Grok already reads `.agents/skills`, and `.claude/skills` while Claude compatibility is on, so the fewest-folder install reaches it. A skill your team committed in `.grok/skills` stays the repo's own: skilllib can copy it into your library and leaves that folder in place. Adding that library skill back writes a second copy in the usual install folder for your agents (see [Adding and removing skills](#adding-and-removing-skills)). Grok still runs the team's `.grok/skills` copy. Claude Code runs the library copy. With `[compat.claude] skills = false`, Grok stops reading `.claude/skills`; skilllib still counts that folder as visible to Grok.
 - **Limits.** No per-repo switch for a global skill. Plugins (`~/.grok/plugins`) stay off until named in `~/.grok/config.toml`, and skilllib doesn't list them yet.
 
 ---
@@ -375,29 +381,32 @@ skilllib status                 this repo's skills, which agents load them, and
 skilllib add | remove <name>    change this repo's skills
 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 update [name...|--all] move to the newest versions (--all: every project)
 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 import <dir>...        add skill folders to your library (--global: all your global skills); a repo that tracks that copy pins the new version
 skilllib global [keep|unkeep]   your global skills; mark the ones you keep global on purpose
 skilllib global move <name> --to <repo>   load a global skill only in those repos
 skilllib new <name> [desc]      create a skill
 
-skilllib usage [--days N]       which skills Claude Code used
+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 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
+skilllib restore [name]         put back something skilllib moved out (copies moved together come back together)
+skilllib unhide <path>          show a hidden project again
+skilllib ui                     open the app (only in a terminal)
 skilllib agent-skill [install|remove]   teach your agents to use skilllib
 skilllib --version
 ```
 
 The repo commands (`status`, `add`, `remove`, `sync`, `outdated`, `update`, `link`, `tidy`) work in a git repo or a folder with `skilllib.json`, and never in your home folder: skills there would load in every repo. Elsewhere they stop with an error. `--all`, `tidy --global` and `status --json` work from any folder; outside a repo, `status --json` lists only the global skills.
 
-Flags: `--force` (overwrite local edits, backed up to `~/.skilllib/edit-backup`), `--allow-tracked` (link into git-tracked folders; skills git doesn't share are still left out), `--days N`, `--json`. For `tidy`: `--dry-run` (preview), `--allow-git` (also change committed files), `<name> --keep <folder>` (the copy that wins when copies differ).
+Flags: `--force` (overwrite local edits, backed up to `~/.skilllib/edit-backup`), `--allow-tracked` (link into git-tracked folders, for that command only; skills git doesn't share are still left out), `--days N`, `--json`. For `tidy`: `--dry-run` (preview), `--allow-git` (also change committed files), `<name> --keep <folder>` (the copy that wins when copies differ).
 
-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, an unknown `tidy` name or `--keep` folder. 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`, a failure prints `{"error": "…"}` on stdout as well as the message on stderr.
+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:
 
@@ -410,8 +419,8 @@ A command exits 1 when it couldn't do all you asked: a skill skipped (not in the
   - the repo's top-level files
 
   Skills that share every attribute are grouped, and attributes at their usual value are left out.
-- **`list --json`**: inside a repo, the library skills the repo already has (names only), and the others with the first sentence of their description.
-- **`add`, `remove`, `sync` and `update`** list each change and the folders it wrote to, so there's nothing left to check.
+- **`list --json`**: inside a repo, the library skills the repo already has (names only), and the others with a short description (its first sentence, or the start of it).
+- **`add`, `remove`, `sync` and `update`** list each change, and (except `remove`) the folders it wrote to, so there's nothing left to check.
 
 The `skilllib` skill runs `status` and `list` as it loads (in Claude Code), so an agent usually answers "which skills can you use here?" in one step.
 
@@ -445,7 +454,7 @@ Environment variables: `SKILLLIB_HOME` moves `~/.skilllib`, `$VISUAL` / `$EDITOR
 
 **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 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.
+**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.
 
 **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.