skills-atlas-cli 0.9.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Search, install and learn AI agent skills from the terminal — powered by the Skills Atlas catalog.",
   "bin": {
     "skills-atlas": "bin/skills.js",

package/src/commands/gaps.js

@@ -29,7 +29,7 @@ const INSTRUCTION = dismissed =>
   `is built for and they haven't installed. For each real recurring need (ignore one-offs and ` +
   `anything already covered): state the pattern + rough frequency as evidence, then recommend the ` +
   `skill — verify it exists with \`skills-atlas search "<intent>"\` or \`skills-atlas info <skill>\`, ` +
-  `and install with \`skills-atlas use <skill> --yes\`.` +
+  `and install with \`skills-atlas use <skill> --yes --project\`.` +
   (dismissed.length ? ` Already dismissed (skip these): ${dismissed.join(', ')}.` : '') +
   ` If nothing clearly recurs, say there are no gaps.`;
 

package/src/commands/suggest.js

@@ -78,7 +78,7 @@ module.exports = async function suggest() {
           if (txt && !/^NONE\b/i.test(txt)) {
             const body = pending.source === 'fallback'
               ? txt // already a full digest for the main agent to judge
-              : `[Skills Atlas — capability gaps] ${txt}\nOffer this to the user only if it genuinely fits — verify with \`skills-atlas info <skill>\`, install with \`skills-atlas use <skill> --yes\`; otherwise stay silent.`;
+              : `[Skills Atlas — capability gaps] ${txt}\nOffer this to the user only if it genuinely fits — verify with \`skills-atlas info <skill>\`, install with \`skills-atlas use <skill> --yes --project\`; otherwise stay silent.`;
             emit(body + langHint(ap.replyLang));
             gapstate.touchNudge(gapstate.activitySignature(recent));
             writeState(file, state);
@@ -136,7 +136,7 @@ module.exports = async function suggest() {
 
     const lines = candidates.map(c => {
       const uc = (c.row.use_case_en || c.row.use_case || '').replace(/\s+/g, ' ').trim().slice(0, 80);
-      return `- ${c.skill}${uc ? ` — ${uc}` : ''}  (details: \`skills-atlas info ${c.skill}\` · use now: \`skills-atlas use ${c.skill} --yes\`)`;
+      return `- ${c.skill}${uc ? ` — ${uc}` : ''}  (details: \`skills-atlas info ${c.skill}\` · use now: \`skills-atlas use ${c.skill} --yes --project\`)`;
     }).join('\n');
     emit(
       `[Skills Atlas autopilot] The user may be doing something one of these installable agent ` +
@@ -144,7 +144,7 @@ module.exports = async function suggest() {
       `genuinely fits what they actually asked:\n${lines}\n` +
       `If one genuinely fits, DON'T just name it: in one line tell the user what it does and why it ` +
       `fits THIS task (it's a curated skill from the Skills Atlas catalog, not something you made up), ` +
-      `then let them choose — activate it now (\`skills-atlas use <skill> --yes\` installs + applies it ` +
+      `then let them choose — activate it now (\`skills-atlas use <skill> --yes --project\` installs + applies it ` +
       `immediately), see what it covers first (\`skills-atlas info <skill>\`), or skip and you'll just ` +
       `do the task yourself. If none fit but the task plainly needs a specialized skill, you may run ` +
       `\`skills-atlas search "<short intent>"\` to look further. If nothing fits, say nothing about this ` +