skilllib 1.7.0 → 1.11.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-c792ea)
+![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)
 
 ```bash
 npx skilllib
@@ -23,7 +23,7 @@ npx skilllib
 
 ## The problem
 
-[Agent skills](https://code.claude.com/docs/en/skills) (folders with a `SKILL.md`) are one of the best ways to teach Claude Code, Cursor, Codex and Zed how *you* work. But they pile up quickly:
+[Agent skills](https://code.claude.com/docs/en/skills) (folders with a `SKILL.md`) are one of the best ways to teach Claude Code, Cursor, Codex, Zed and Grok how *you* work. But they pile up quickly:
 
 - **`npx skills add`** drops skills into `~/.agents/skills`.
 - **Plugins** bring their own.
@@ -35,7 +35,7 @@ A few weeks later:
 
 - **🌍 Global skills load everywhere.** Everything in `~/.claude/skills` or `~/.agents/skills` loads in **every repo, in every session**. Your agent reads the name and description of your Stripe skill while fixing Terraform in your infra repo. That costs context, and skills fire when they shouldn't.
 - **👯 Duplicates.** The same skill arrives through `npx skills` *and* a plugin *and* a copy in the repo, and your agent sees it twice.
-- **🙈 Each agent looks somewhere else.** Claude Code reads `.claude/skills`; Codex and Zed read `.agents/skills`; Cursor reads both. The skills your team committed to `.agents/skills` are invisible to Claude Code.
+- **🙈 Each agent looks somewhere else.** Claude Code reads `.claude/skills`; Codex and Zed read `.agents/skills`; Cursor reads both. Grok reads `.grok/skills` and `.agents/skills`, and by default the Claude and Cursor folders too. The skills your team committed to `.agents/skills` are invisible to Claude Code.
 - **🧟 Copies drift.** You improved a skill in one repo; the other five still have the old version.
 - **🤷 No overview.** Which skills does this repo actually have? Where did each one come from? Is it committed, or only on my laptop? Does anyone use it?
 
@@ -53,8 +53,8 @@ Most agents can't turn off a global skill for just one repo. Claude Code can, bu
   - which agents load it
   - whether it's committed to git or gitignored
   - how often it was used
-- **💬 Talk to your agents about your skills.** Ask Claude Code, Cursor or Codex "which skills can you use here, and where do they come from?" or "which of my skills should this repo use?". They answer with skilllib.
-- **✦ Ask an agent.** Copy a ready-made prompt with all of that data, and let Claude Code, Cursor or Codex tell you what to keep, move or delete.
+- **💬 Talk to your agents about your skills.** Ask Claude Code, Cursor, Codex or Grok "which skills can you use here, and where do they come from?" or "which of my skills should this repo use?". They answer with skilllib.
+- **✦ Ask an agent.** Copy a ready-made prompt with all of that data, and let Claude Code, Cursor, Codex or Grok tell you what to keep, move or delete.
 - **🛟 Nothing is lost.** Every removal goes to a backup you can restore with one key.
 
 Everything runs locally: no server, no account, no network calls.
@@ -72,7 +72,7 @@ It needs **Node.js 22+** and works on macOS and Linux. Windows support is newer:
 
 On first run, skilllib asks two things:
 
-1. **Which agents you use:** Claude Code, Cursor, Codex, Zed. The ones installed on your machine are pre-selected.
+1. **Which agents you use:** Claude Code, Cursor, Codex, Zed, Grok. The ones installed on your machine are pre-selected.
 2. **Where your projects live**, e.g. `~/Projects`. It finds every git repo in there, and rescans each time it opens.
 
 Then a good first session looks like this:
@@ -93,6 +93,7 @@ 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. |
 | **Settings** | Your agents and the skilllib skill for them, your project folders, hidden repos, and backups. |
@@ -116,7 +117,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 · `untracked`: only on this machine · `global` (`global ✓`: global on purpose) · `⧉ plugin` · `claude.ai` · `cursor` |
+| 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` |
 | Uses | Claude Code uses in this repo, last 30 days |
 | Issue | The worst of its issues; the details show them all |
 
@@ -142,10 +143,10 @@ What skilllib flags:
 
 ### Adding and removing skills
 
-- **+ Add a skill…** searches your library. Its last rows create a new skill (it opens in `$EDITOR`, and goes into the repo when you close it) or copy a prompt for an agent to write it.
-- **Adding** 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>`.
+- **+ Add a skill…** searches your library. Tick several with `space` and add them in one go; a plugin's skills (e.g. ponytail and its `ponytail-*` commands) sit under one row that ticks or adds them all. Its last rows create a new skill (it opens in `$EDITOR`, and goes into the repo when you close it) or copy a prompt for an agent to write it.
+- **Adding** 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. Grok reads `.agents/skills` and, by default, `.claude/skills`, so it never needs its own copy.
+  - 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.
 - **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.
@@ -174,15 +175,39 @@ Edit a skill once in **Your skills** (Enter → *Edit SKILL.md*). Every repo tha
 
 **Global** lists everything that loads in every repo. Each of your global skills you haven't decided about is flagged **Not reviewed**, with three choices:
 
-- **Move it to the repos that need it…**: tick the repos (the ones where Claude Code used it are pre-ticked). It goes into your library and those repos, and stops loading globally. If a repo commits a folder one of your agents needs a link in (often `.claude/skills`), skilllib asks before adding it there.
+- **Move it to the repos that need it…**: tick the repos (the ones where Claude Code used it are pre-ticked). It goes into your library and those repos, and stops loading globally. If a repo commits a folder one of your agents needs a link in (often `.claude/skills`), skilllib asks before adding it there. From the command line: `skilllib global move <name>... --to <repo>...`.
 - **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.
 
-Vendor skills (plugins, claude.ai, Cursor built-ins) are managed at their source: `/plugin` in Claude Code, or claude.ai's settings.
+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**.
 
-**Replacing a plugin with library skills:** on a plugin's skill or group, **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 (`claude plugin uninstall`, keeping its saved data; Settings › Backups reinstalls it). A plugin can't be half removed, so it's all its skills at once; the confirmation says what else it brings (commands, agents, hooks, MCP servers) 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 and tells you to remove the plugin on claude.ai.
+### Plugins
+
+Plugins are a big part of what agents load (one plugin can bring dozens of skills), so they get their own place: one row per plugin, not per skill.
+
+| Column | Meaning |
+|---|---|
+| Plugin | Its name; the details show `name@marketplace` |
+| ✻ ⬡ | Claude Code or Cursor |
+| 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** |
+
+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.
+
+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.
+- **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.
+- **Review prompt** for the plugin's skills, and **Open its folder**.
+
+Cursor's plugins are listed read-only: Cursor doesn't record which plugins are on in a file skilllib can read, so turn them off in Cursor (Settings › Plugins). A repo's overview shows which plugins load there.
 
 ### Ask an agent to review your skills
 
@@ -195,7 +220,7 @@ Not sure what to keep? **Review prompt** puts a ready-to-paste prompt on your cl
 - duplicates
 - your project list, so the agent can check each repo's stack
 
-Paste it into Claude Code, Cursor or Codex. You get back **keep global / move to projects / delete / turn off at the vendor** for each skill, as a table plus JSON.
+Paste it into Claude Code, Cursor, Codex or Grok. You get back **keep global / move to projects / delete / turn off at the vendor** for each skill, as a table plus JSON.
 
 It's in every skill's actions, in a repo's **⋯** menu (all its skills), and at the top of Global (all your global skills).
 
@@ -244,7 +269,7 @@ skilllib never really deletes anything you can't get back. What it removes goes
 - removed global skills go to `~/.skilllib/global-backup`
 - copies replaced by a link go to `~/.skilllib/tidy-backup`
 - local edits that `skilllib doctor` discards, or that `--force` overwrites (`add`, `update`, `sync`), go to `~/.skilllib/edit-backup`
-- removed plugins are listed too; restoring one reinstalls it
+- uninstalled plugins are listed too; restoring one reinstalls it, in its repo for a project install
 
 ---
 
@@ -254,10 +279,10 @@ 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`, `.cursor/skills`, `.codex/skills` | Agents working in that repo |
+| **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 |
-| **Global folders** | `~/.claude/skills`, `~/.agents/skills` (`npx skills add` installs here), `~/.codex/skills`, `~/.cursor/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) | Every repo (a repo's `.claude/settings.json` can turn a plugin on or off just there); only the vendor can remove them |
+| **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 |
 
 ### ✻ Claude Code · [docs](https://code.claude.com/docs/en/skills)
@@ -285,7 +310,7 @@ A skill is a folder with a `SKILL.md`. These are all the places your agents load
 - **Where it looks.**
   - Project: `.agents/skills` and `.cursor/skills`, including nested ones, which apply only to files inside them.
   - Your home folder: `~/.agents/skills` and `~/.cursor/skills`.
-  - For compatibility: `.claude/skills`, `.codex/skills`, `.grok/skills` and the same three in your home folder. The setting **Include Third-Party Plugins, Skills, and Other Configs** (on by default) turns these on, and it also imports your enabled Claude Code plugins. It always uses your home folder: `CLAUDE_CONFIG_DIR` and `CODEX_HOME` don't apply. skilllib leaves `.grok/skills` alone: it's Grok's folder, and skilllib can't tell what Grok needs.
+  - For compatibility: `.claude/skills`, `.codex/skills`, `.grok/skills` and the same three in your home folder. The setting **Include Third-Party Plugins, Skills, and Other Configs** (on by default) turns these on, and it also imports your enabled Claude Code plugins. It always uses your home folder: `CLAUDE_CONFIG_DIR` and `CODEX_HOME` don't apply. skilllib still doesn't install into `.grok/skills` or tidy it for Cursor. That folder is where a team commits skills for Grok, and a copy that lives only there stays invisible to Cursor in skilllib.
   - Also marketplace plugins and Cursor's built-ins (`~/.cursor/skills-cursor`). Cloud Agents only see `~/.cursor/skills`.
   - It finds every `SKILL.md` up to 10 folders deep. It skips dot folders, `node_modules`, `dist` and `build`, and Codex's bundled skill names (like `skill-creator`) under `.codex/skills`.
 - **How it uses them.** Descriptions decide relevance, and the full content loads on use; `/` runs one. `paths:` globs limit a skill to matching files, and `disable-model-invocation: true` makes it manual.
@@ -310,6 +335,18 @@ A skill is a folder with a `SKILL.md`. These are all the places your agents load
 - **Where it looks.** `<worktree>/.agents/skills` (trusted worktrees only) and `~/.agents/skills`, nothing else (verified in its source, October 2026). Only direct child folders count, and on a name collision the project's skill wins.
 - **How it uses them.** The agent sees a catalog of names and descriptions; `/` or `@skill` runs one. Changes apply without a restart.
 
+### ✶ Grok · user guide, Skills
+
+- **Where it looks.** Higher priority wins, and the same name is kept once. A project folder beats a home folder. Inside each, the order is `.grok`, then `.agents`, then `.claude`, then `.cursor`. It walks from the working folder up to the repo root:
+  1. `.grok/skills`, then `.agents/skills`, then `.claude/skills` and `.cursor/skills` (those two are on by default)
+  2. `~/.grok/skills` (`GROK_HOME` moves `~/.grok`), then `~/.agents/skills`, then `~/.claude/skills` and `~/.cursor/skills`
+  3. `~/.grok/bundled/skills` (a project or user skill with the same name overrides these)
+
+  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.
+- **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.
+
 ---
 
 ## Command line
@@ -320,7 +357,7 @@ Everything the app does also works as a command, for scripts and CI:
 skilllib                        open the app (prints `status` when piped)
 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)
+skilllib harnesses [id...]      show or set your agents (claude-code cursor codex zed grok)
 
 skilllib status                 this repo's skills, which agents load them, and issues
 skilllib add | remove <name>    change this repo's skills
@@ -333,10 +370,12 @@ skilllib tidy [--all|--global]  one real copy per skill, plus only the links you
 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 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 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 agent-skill [install|remove]   teach your agents to use skilllib
 skilllib --version
@@ -348,13 +387,13 @@ Flags: `--force` (overwrite local edits, backed up to `~/.skilllib/edit-backup`)
 
 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.
 
-**`--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`, `add`, `remove`, `sync`, `update`, `import` 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` and `agent-skill`. 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
   - skills in subfolders (`nested`, e.g. monorepo packages), with their folder
   - the global skills, grouped by where they come from, with the plugins the repo's `.claude/settings.json` turns on or off
-  - every problem skilllib found here, with its fix
+  - every problem skilllib found here, with its fix or choices and an id for `skilllib apply`
   - how often Claude Code used each skill here
   - the repo's top-level files
 
@@ -364,6 +403,17 @@ A command exits 1 when it couldn't do all you asked: a skill skipped (not in the
 
 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.
 
+**TypeScript types.** The package ships a type for each command's JSON (`StatusJson`, `ListJson`, `ChangesJson`, `DoctorJson`…). It has types only, no runtime API:
+
+```ts
+import { execFileSync } from "node:child_process";
+import type { StatusJson } from "skilllib";
+
+const status: StatusJson = JSON.parse(execFileSync("skilllib", ["status", "--json"], { encoding: "utf-8" }));
+```
+
+A field is only removed or changed in a major version.
+
 ## Files
 
 | Path | What |
@@ -373,11 +423,11 @@ The `skilllib` skill runs `status` and `list` as it loads (in Claude Code), so a
 | `~/.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/`, `tidy-backup/`, `edit-backup/` | Everything skilllib removed, restorable from Settings › Backups |
-| `~/.skilllib/plugin-backup.json` | Plugins skilllib uninstalled, so Settings › Backups can reinstall them |
+| `~/.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 |
 | `~/.claude/skills/skilllib/` | The skill that lets your agents use skilllib (`agent-skill install`) |
 
-Environment variables: `SKILLLIB_HOME` moves `~/.skilllib`, `$VISUAL` / `$EDITOR` set the editor, and `CLAUDE_CONFIG_DIR` and `CODEX_HOME` are honored.
+Environment variables: `SKILLLIB_HOME` moves `~/.skilllib`, `$VISUAL` / `$EDITOR` set the editor, `CLAUDE_CONFIG_DIR` is honored for Claude Code, `CODEX_HOME` for Codex, and `GROK_HOME` for Grok. Grok does not honor `CLAUDE_CONFIG_DIR`.
 
 ## FAQ
 
@@ -385,10 +435,12 @@ Environment variables: `SKILLLIB_HOME` moves `~/.skilllib`, `$VISUAL` / `$EDITOR
 
 **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.
+**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.
 
 **What's not supported yet?**
-- 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.
+- Grok plugins: they stay off until named in `~/.grok/config.toml`, and skilllib doesn't read that list yet.
+- 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.
 - Installing new skills straight from GitHub is coming. For now, `skilllib import <folder>` or copy one from a repo.
 
@@ -406,14 +458,10 @@ npm link                                     # use your checkout as `skilllib`
 
 How the TUI is designed, and why: [docs/DESIGN.md](docs/DESIGN.md).
 
-**Releasing:**
-1. Bump `version` in `package.json` and merge to `main`.
-2. Tag and push:
-   ```bash
-   git tag v1.7.0 && 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.
+**Releasing:** automatic, with [release-please](https://github.com/googleapis/release-please). Don't edit `version` by hand.
+1. Write commits (and PR titles) as [Conventional Commits](https://www.conventionalcommits.org/): `fix:` → patch, `feat:` → minor, `feat!:` or a `BREAKING CHANGE:` footer → major. `docs:`, `ci:`, `chore:`, `test:` and `refactor:` don't release.
+2. After each merge to `main`, release-please keeps one PR, **chore(main): release X.Y.Z**, up to date with the next version and its `CHANGELOG.md`.
+3. Merge that PR when you want to release. It tags `vX.Y.Z` and creates the GitHub release; CI then tests, builds and publishes to npm through [trusted publishing](https://docs.npmjs.com/trusted-publishers) (no token; provenance is automatic).
 
 The earlier registry-server version (Next.js, Postgres, S3) lives on the `archive/registry-server` branch.