skills-atlas-cli 0.8.9 → 0.9.1

package/README.md

@@ -70,9 +70,12 @@ skills-atlas doctor                            # health check: orphans, drift, l
 skills-atlas kit                               # detect this project & install the right skills for it
 skills-atlas sync                              # reproduce a project's kit (skills-atlas.kit.json)
 
-# 🤖 Autopilot & capability gaps   (opt-in)
+# 🤖 Autopilot, gaps & cleanup   (opt-in)
 skills-atlas hook on                           # Claude proactively offers a fitting skill as you work
+skills-atlas hook lang en|zh                   # language the autopilot replies in (default English)
+skills-atlas hook model                        # which model powers gaps/cleanup (default Haiku)
 skills-atlas gaps                              # Claude spots kinds of work you keep doing without a skill
+skills-atlas prune                             # Claude flags installed skills you no longer use
 
 # 🌐 Catalog & sources
 skills-atlas categories                        # the 20 top-level categories
@@ -86,44 +89,37 @@ skills-atlas mcp                               # run as an MCP server (any MCP c
 
 **⛓ Workflows, not just skills.** Many skills belong to a curated chain (e.g.
 `brainstorming → writing-plans → executing-plans → …`). `install <skill> --chain`
-installs the whole pipeline in one archive download, ready to run in order.
+installs the whole pipeline in one step, ready to run in order.
 
 **📦 Project kits.** `skills-atlas kit` detects what this project is (frontend / backend /
 data / infra) and installs a tailored set (a universal dev workflow plus archetype
 add-ons) into `./.claude/skills/`, then writes a committable `skills-atlas.kit.json`.
 A teammate runs `skills-atlas sync` to reproduce it exactly.
 
-Output is English by default; add `--zh` for Chinese, or `--json` to any command for machine-readable output.
-After installing a skill, start a new Claude Code session to load it.
-
-## How install works
-
-The real value is the **catalog**: `search` / `info` / `categories` work fully
-offline and map *which* skill fits. It's function-organized, bilingual, tagged with
-use-case / when-to-use / personas / ⛓ chains. That's what `npx skills add` and
-GitHub search don't give you.
+**Where skills land.** Running `install` / `use` yourself installs **globally**
+(`~/.claude/skills/`, every project) — for general workflows you want everywhere. Skills
+suggested by autopilot, installed via the Claude Code plugin, or set up by `kit` go into
+**this project** (`./.claude/skills/`, committable for teammates). Override either way
+with `--global` / `--project`.
 
-On top of that, `install` can place a skill straight into `.claude/skills/`:
+Output is English by default; add `--zh` for Chinese.
+After installing a skill, start a new Claude Code session to load it.
 
-- For a repo that exposes a **per-skill folder**, it downloads only that folder
-  (via the repo archive, with **no GitHub API rate limit**) into
-  `<target>/.claude/skills/<skill>/`, not the whole repo.
-- Several sources? The best installable one is auto-picked. Pass `--source <id>` to
-  choose, `--yes` for non-interactive runs.
-- Other sources (whole-repo / marketplace) print their official command instead
-  (e.g. `npx skills add owner/repo`).
-- `GITHUB_TOKEN` is only needed if you fall back to the API and hit its 60/h limit.
+## Why a catalog
 
-## Keeping the catalog fresh
+`search` / `info` / `categories` work fully offline and tell you *which* skill fits —
+organized by function, bilingual, tagged with use-case, when-to-use, personas and ⛓
+chains. `install` then drops just that skill's folder into `.claude/skills/` (not the
+whole repo); when several repos offer the same skill, the best one is picked for you.
 
-The catalog ships inside the package and works offline. `skills-atlas update` pulls
-the latest from the public feed (cached under `~/.cache/skills-atlas/`).
+The catalog ships with the tool and works offline, and refreshes itself in the
+background so new skills show up on their own. Run `skills-atlas update` to pull the
+latest on demand.
 
-## Private / org catalog sources
+## Your org's private skills
 
-Point the CLI at your organization's own catalog (a `data.json` in the same
-schema) so internal skills show up in `search` / `info` / `install` / `kit`
-alongside the public Atlas:
+Point the CLI at your organization's own catalog so internal skills show up in
+`search` / `info` / `install` / `kit` alongside the public Atlas:
 
 ```bash
 skills-atlas registry add https://skills.acme.internal/data.json   # or a local path
@@ -131,10 +127,7 @@ skills-atlas registry list
 skills-atlas registry remove https://skills.acme.internal/data.json
 ```
 
-Private skills **merge** with the public catalog (a private source wins a same-name
-clash). Sources are cached locally and merged offline. For a private URL behind
-auth, set `SKILLS_ATLAS_TOKEN` (sent as a Bearer header); in CI,
-`SKILLS_ATLAS_SOURCES=url1,url2` adds sources without touching config.
+Private skills merge with the public catalog (your own wins a name clash) and are cached locally.
 
 ## In Claude Code
 
@@ -149,9 +142,9 @@ Just describe what you need, or use `/skills-atlas:skill-search`, `:skill-info`,
 
 ## In any MCP client
 
-`skills-atlas mcp` runs a zero-dependency [MCP](https://modelcontextprotocol.io)
-server over stdio, so any MCP-capable client (Claude Desktop, other agents) can use
-the catalog. Add it to your client's config:
+`skills-atlas mcp` runs an [MCP](https://modelcontextprotocol.io) server so any
+MCP-capable client (Claude Desktop, other agents) can use the catalog. Add it to your
+client's config:
 
 ```json
 { "mcpServers": { "skills-atlas": { "command": "npx", "args": ["-y", "skills-atlas-cli", "mcp"] } } }
@@ -164,37 +157,35 @@ anywhere.
 ## Autopilot (opt-in): the right skill finds you
 
 ```bash
-skills-atlas hook on      # enable    (skills-atlas hook off / status)
+skills-atlas hook on      # turn it on   (hook off / hook status)
+```
+
+With autopilot on, whenever what you're doing lines up with a catalog skill you don't
+have, Claude offers it — explained, with one tap to use it now, see what it covers, or
+skip. You don't have to know the skill exists. It's **off by default**, **quiet** (stays
+silent on greetings and generic asks, never repeats itself, never suggests a skill you
+already have), and **safe** (never auto-installs; a hiccup never blocks your prompt).
+
+Two more proactive helpers:
+
+- **🔭 Capability gaps** — `skills-atlas gaps` notices the recurring kinds of work you
+  keep doing without a skill, and recommends one.
+- **🧹 Cleanup** — `skills-atlas prune` flags installed skills you no longer use and
+  offers to remove them (never on its own; recent installs are left alone).
+
+Tune it to taste:
+
+```bash
+skills-atlas hook suggest on|off    # the per-prompt suggestions
+skills-atlas hook gaps on|off       # gap recommendations            (on by default)
+skills-atlas hook prune on|off      # cleanup suggestions            (off by default)
+skills-atlas hook model [name]      # which model powers gaps/cleanup   (default Haiku)
+skills-atlas hook lang en|zh        # the language it replies in        (default English)
 ```
 
-Registers a Claude Code `UserPromptSubmit` hook. When what you ask matches the
-territory of a catalog skill you don't have, the hook hands Claude a short
-shortlist of candidates and **Claude decides** whether any genuinely fits. If it
-does, Claude explains **what it does and why it fits your task**, then offers a choice:
-use it now, see what it covers first (`skills-atlas info`), or skip. You don't
-have to know the skill exists. The split is deliberate: the hook does **recall**
-(a distinctive-word match against the catalog, so the right skill is on the
-table), Claude does **precision** (it understands your intent and stays silent
-unless one truly fits, or searches further itself). It's:
-
-- **Off by default.** You turn it on explicitly; `hook off` removes it cleanly.
-- **Quiet.** Only fires on a distinctive match (greetings and generic actions
-  like "fix the typo" stay silent), never for an already-installed skill, never
-  the same skill twice, with a cooldown between suggestions. Claude is the
-  final filter on relevance.
-- **Local and private.** Your prompt is matched against the bundled catalog
-  on your machine; nothing is sent anywhere.
-- **Safe.** Never auto-installs (always your call), and fails open (a hook
-  error never blocks your prompt).
-
-**🔭 Capability gaps.** `skills-atlas gaps` shows Claude your *recent activity* and
-lets **Claude** spot the recurring kinds of work you keep doing that no installed
-skill covers yet, then recommend one with the pattern as evidence. We don't guess
-with heuristics; we just give Claude the memory it lacks (your recent prompts, read
-from Claude Code's own local transcripts; **nothing is stored or sent**) plus the
-catalog. With the hook on, it also nudges in-conversation now and then. The two
-layers are independent: `skills-atlas hook suggest on|off` (per-prompt) and
-`skills-atlas hook gaps on|off` (the proactive nudge).
+The per-prompt suggestions are matched on your own machine and sent nowhere. The gaps
+and cleanup helpers hand your recent activity to the model you picked (the same provider
+Claude Code already uses) to judge it.
 
 ## License
 

package/bin/skills.js

@@ -15,6 +15,7 @@ const registry = require('../src/commands/registry');
 const suggest = require('../src/commands/suggest');
 const hook = require('../src/commands/hook');
 const gaps = require('../src/commands/gaps');
+const gapAnalyze = require('../src/commands/gap-analyze');
 const prune = require('../src/commands/prune');
 const update = require('../src/commands/update');
 const mcp = require('../src/commands/mcp');
@@ -23,7 +24,7 @@ const { categories, list } = require('../src/commands/categories');
 const VERSION = require('../package.json').version;
 // `use` = install + activate inline (emit the SKILL.md so an agent follows it now).
 const use = argv => install([...argv, '--inline']);
-const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, prune, update, categories, list, registry, mcp };
+const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, 'gap-analyze': gapAnalyze, prune, update, categories, list, registry, mcp };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -75,7 +76,9 @@ async function main() {
   }
   // Opportunistic, non-blocking background catalog refresh so new skills appear over
   // time without a manual `update`. Skipped for `update` itself; fully fail-silent.
-  if (sub !== 'update') { try { require('../src/data').maybeBackgroundRefresh(); } catch { /* ignore */ } }
+  if (sub !== 'update' && sub !== 'gap-analyze' && !process.env.SKILLS_ATLAS_SUBCALL) {
+    try { require('../src/data').maybeBackgroundRefresh(); } catch { /* ignore */ }
+  }
   await cmd(rest);
 }