skills-atlas-cli 0.8.0 → 0.8.4

package/README.md

@@ -3,57 +3,43 @@
 [![npm](https://img.shields.io/npm/v/skills-atlas-cli)](https://www.npmjs.com/package/skills-atlas-cli)
 [![license](https://img.shields.io/npm/l/skills-atlas-cli)](https://github.com/Zita-Go/Skills-Atlas/blob/main/LICENSE)
 
-**Stop guessing which agent skill to use.** Find, install, and learn the right
-specialized skill for the task — in seconds, straight into Claude Code.
+**Find, install, and use the right AI agent skill for any task, right inside Claude
+Code.** Stop guessing which skill fits or copy-pasting from random repos. Search a
+curated catalog of **800+ skills** and drop the right one into `.claude/skills/` in seconds.
 
-Powered by the [**Skills Atlas**](https://zita-go.github.io/Skills-Atlas/) catalog:
-hundreds of Claude Code / Codex skills across 100+ source repos, organized by what
-they actually do.
+> **New to "skills"?** A skill is a reusable `SKILL.md` instruction pack that teaches
+> Claude Code a specialized workflow: systematic debugging, pre-mortems, SEO audits,
+> PDF translation, and hundreds more. This tool finds and installs them for you.
 
-<img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/cli-demo.png" alt="skills-atlas: search then install a skill" width="760">
-
-## 🌐 Browse the whole catalog online
+### Two ways to get the right skill
 
-<table>
-<tr>
-<td><a href="https://zita-go.github.io/Skills-Atlas/"><img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/screenshot-light.png" alt="Skills Atlas — light theme" width="400"></a></td>
-<td><a href="https://zita-go.github.io/Skills-Atlas/"><img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/screenshot-dark.png" alt="Skills Atlas — dark theme" width="400"></a></td>
-</tr>
-</table>
+1. **🔍 Find and install it.** Search the catalog, then `use` it. It's live in Claude Code in seconds.
+2. **🤖 Let it find you.** Turn on autopilot and Claude offers the fitting skill as you work, no searching.
 
-**[→ zita-go.github.io/Skills-Atlas](https://zita-go.github.io/Skills-Atlas/)** —
-explore by category, then install what you find with the CLI.
+<img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/cli-demo.png" alt="skills-atlas: search then install a skill" width="760">
 
-## Install
+## Quickstart
 
 ```bash
-npm install -g skills-atlas-cli      # adds the `skills-atlas` command (alias: `sa`)
-```
-
-Or run it without installing: `npx skills-atlas-cli search seo`
-
-## How you'll use it
+npm install -g skills-atlas-cli      # adds the `skills-atlas` command (alias sa). Or run any command with `npx`.
 
-Three ways to reach the same catalog — pick whichever fits the moment:
+skills-atlas search "stress test my launch plan"   # pre-mortem tops the results
+skills-atlas use pre-mortem                          # installs it, prints its SKILL.md so Claude applies it now
+skills-atlas hook on                                 # optional: turn on autopilot, skip the search next time
+```
 
-| Mode | Best when | Get going |
-|---|---|---|
-| **Manual** | you want to browse and grab skills yourself | `skills-atlas search <task>` → `skills-atlas use <skill>` |
-| **In Claude Code** | you'd rather just ask Claude in-conversation | install the [plugin](#in-claude-code), then describe your task |
-| **🤖 Autopilot** | you want the right skill to find *you* | `skills-atlas hook on` — Claude offers a fitting skill as you work |
+Now `pre-mortem` lives in `~/.claude/skills/` and auto-loads in new Claude Code sessions.
 
-**60-second quickstart:**
+## 🌐 Browse the catalog online
 
-```bash
-npm install -g skills-atlas-cli
-skills-atlas search "stress test my launch plan"   # → pre-mortem tops the results
-skills-atlas use pre-mortem                         # install + activate now (prints its SKILL.md)
-skills-atlas hook on                                # optional — let the right skill find you from here on
-```
+<table>
+<tr>
+<td><a href="https://zita-go.github.io/Skills-Atlas/"><img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/screenshot-light.png" alt="Skills Atlas — light theme" width="400"></a></td>
+<td><a href="https://zita-go.github.io/Skills-Atlas/"><img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/screenshot-dark.png" alt="Skills Atlas — dark theme" width="400"></a></td>
+</tr>
+</table>
 
-`use` drops the skill into `~/.claude/skills/` and prints it for the task at hand; it
-auto-loads in new Claude Code sessions. With autopilot on, you don't even need to
-`search` — describe your task and Claude surfaces the skill if one fits.
+Explore the catalog visually at **[zita-go.github.io/Skills-Atlas](https://zita-go.github.io/Skills-Atlas/)**, then install what you find with the CLI.
 
 ## Usage
 
@@ -70,7 +56,7 @@ skills-atlas info brainstorming
 skills-atlas install brainstorming             # → ~/.claude/skills/   (default, all projects)
 skills-atlas install brainstorming --project   # → ./.claude/skills/   (this project only)
 skills-atlas install brainstorming --chain     # install the whole ⛓ workflow it belongs to
-skills-atlas use brainstorming                 # install AND activate now — prints SKILL.md, no restart
+skills-atlas use brainstorming                 # install + activate now (prints SKILL.md, no restart)
 skills-atlas install brainstorming --dry-run   # preview the files, write nothing
 
 # 🗂️ Manage what you've installed   (like a package manager)
@@ -84,10 +70,18 @@ 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)
 
-# 🌐 Catalog
+# 🤖 Autopilot & capability gaps   (opt-in)
+skills-atlas hook on                           # Claude proactively offers a fitting skill as you work
+skills-atlas gaps                              # Claude spots kinds of work you keep doing without a skill
+
+# 🌐 Catalog & sources
 skills-atlas categories                        # the 20 top-level categories
 skills-atlas list marketing                    # skill groups within a category
+skills-atlas registry add <url|path>           # add a private org catalog source (merges into search/install)
 skills-atlas update                            # pull the latest catalog
+
+# 🔌 Integrations
+skills-atlas mcp                               # run as an MCP server (any MCP client: Claude Desktop, …)
 ```
 
 **⛓ Workflows, not just skills.** Many skills belong to a curated chain (e.g.
@@ -95,8 +89,8 @@ skills-atlas update                            # pull the latest catalog
 installs the whole pipeline in one archive download, 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`.
+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.
@@ -105,16 +99,16 @@ 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 — function-organized, bilingual, tagged with
+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.
 
 On top of that, `install` can place a skill straight into `.claude/skills/`:
 
 - For a repo that exposes a **per-skill folder**, it downloads only that folder
-  (via the repo archive — **no GitHub API rate limit**) into
+  (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 — `--source <id>` to
+- 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`).
@@ -127,8 +121,8 @@ the latest from the public feed (cached under `~/.cache/skills-atlas/`).
 
 ## Private / org catalog sources
 
-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`
+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:
 
 ```bash
@@ -144,8 +138,8 @@ auth, set `SKILLS_ATLAS_TOKEN` (sent as a Bearer header); in CI,
 
 ## In Claude Code
 
-A thin [Claude Code plugin](./plugin) lets Claude do all of this in-conversation —
-just describe what you need, or use `/skills-atlas:skill-search`, `:skill-info`,
+A thin [Claude Code plugin](./plugin) lets Claude do all of this in-conversation.
+Just describe what you need, or use `/skills-atlas:skill-search`, `:skill-info`,
 `:skill-install`:
 
 ```text
@@ -164,10 +158,10 @@ the catalog. Add it to your client's config:
 ```
 
 It exposes four tools: **search_skills**, **skill_info**, **install_skill**, and
-**list_categories** — discover, inspect, install, and browse the catalog from
+**list_categories**. Discover, inspect, install, and browse the catalog from
 anywhere.
 
-## Autopilot (opt-in) — the right skill finds you
+## Autopilot (opt-in): the right skill finds you
 
 ```bash
 skills-atlas hook on      # enable    (skills-atlas hook off / status)
@@ -175,29 +169,29 @@ skills-atlas hook on      # enable    (skills-atlas hook off / status)
 
 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 — and
-if so, explains **what it does and why it fits your task**, then offers a choice:
+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
+- **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 — and Claude is the
+  the same skill twice, with a cooldown between suggestions. Claude is the
   final filter on relevance.
-- **local & private** — your prompt is matched against the bundled catalog
+- **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
+- **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
+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
+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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.8.0",
+  "version": "0.8.4",
   "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/args.js

@@ -21,6 +21,7 @@ const ALL = {
   zh: { type: 'boolean' },
   all: { type: 'boolean' },
   inline: { type: 'boolean' },
+  verbose: { type: 'boolean' },
   archetype: { type: 'string' },
   update: { type: 'boolean' },
   name: { type: 'string' },

package/src/commands/categories.js

@@ -31,11 +31,17 @@ async function list(argv) {
 
   const en = !values.zh;
   const filter = (positionals.join(' ') || values.category || '').trim();
+  // A bare number means "that numbered category" — match the "N." prefix exactly,
+  // so `list 4` doesn't also pull in "14." via loose substring.
+  const numFilter = /^\d+$/.test(filter) ? new RegExp(`^${filter}\\b`) : null;
   const { data } = loadData({ quiet: values.json });
 
   const out = [];
   for (const s of data.sections) {
-    if (filter && !(loose(s.title, filter) || loose(s.title_en, filter))) continue;
+    const hit = !filter
+      || (numFilter ? (numFilter.test(s.title_en || '') || numFilter.test(s.title || ''))
+        : (loose(s.title, filter) || loose(s.title_en, filter)));
+    if (!hit) continue;
     out.push({
       section: en ? (s.title_en || s.title) : s.title,
       groups: s.subsections.flatMap(ss => ss.rows.map(r => ({

package/src/commands/doctor.js

@@ -34,8 +34,8 @@ module.exports = async function doctor(argv) {
       const dir = path.join(root, skill);
       if (!fsu.dirExists(dir)) { findings.push({ scope: s.name, skill, level: 'warn', msg: 'recorded but folder missing on disk' }); continue; }
       if (!fs.existsSync(path.join(dir, 'SKILL.md'))) findings.push({ scope: s.name, skill, level: 'error', msg: 'no SKILL.md in folder' });
-      if (!data.vendors[e.source] || !rowsFor(idx.skillIndex, skill).length) findings.push({ scope: s.name, skill, level: 'info', msg: 'no longer in the catalog' });
-      if (e.scripts) findings.push({ scope: s.name, skill, level: 'info', msg: `ships ${e.scripts} script file(s) — review` });
+      if (!data.vendors[e.source] || !rowsFor(idx.skillIndex, skill).length) findings.push({ scope: s.name, skill, level: 'info', msg: `no longer in the catalog (keep it, or: skills-atlas remove ${skill})` });
+      if (e.scripts) findings.push({ scope: s.name, skill, level: 'info', msg: `ships ${e.scripts} script file(s) — review before trusting: ${fsu.tildify(dir)}` });
       const vendor = data.vendors[e.source];
       if (vendor && vendor.license && RISKY_LICENSE.test(vendor.license)) findings.push({ scope: s.name, skill, level: 'warn', msg: `license: ${vendor.license}` });
     }

package/src/commands/hook.js

@@ -45,10 +45,16 @@ module.exports = async function hook(argv) {
     const ap = registry.getAutopilot();
     if (values.json) { console.log(JSON.stringify({ enabled: on, suggest: ap.suggest, gapAlerts: ap.gapAlerts, settings: p })); return; }
     console.log(`autopilot hook: ${on ? green('on') : dim('off')}   ${dim(p)}`);
-    console.log(`  per-prompt suggest: ${ap.suggest ? green('on') : dim('off')}   ${dim('(skills-atlas hook suggest on|off)')}`);
-    console.log(`  gap alerts:         ${ap.gapAlerts ? green('on') : dim('off')}   ${dim('(skills-atlas hook gaps on|off)')}`);
-    if (on) console.log(dim('  review gaps: skills-atlas gaps'));
-    if (!on) console.log(dim('enable: skills-atlas hook on'));
+    if (on) {
+      console.log(`  per-prompt suggest: ${ap.suggest ? green('on') : dim('off')}   ${dim('(skills-atlas hook suggest on|off)')}`);
+      console.log(`  gap alerts:         ${ap.gapAlerts ? green('on') : dim('off')}   ${dim('(skills-atlas hook gaps on|off)')}`);
+      console.log(dim('  review gaps: skills-atlas gaps'));
+    } else {
+      // Hook isn't registered, so these sub-toggles don't do anything yet — don't
+      // imply the autopilot is running. Show them dimmed with the caveat.
+      console.log(dim(`  (suggest ${ap.suggest ? 'on' : 'off'}, gap alerts ${ap.gapAlerts ? 'on' : 'off'} — they take effect once you run 'skills-atlas hook on')`));
+      console.log(dim('enable: skills-atlas hook on'));
+    }
     return;
   }
 
@@ -71,6 +77,7 @@ module.exports = async function hook(argv) {
     if (arr.some(isOurs)) { console.log(dim('autopilot already on.')); return; }
     settings.hooks.UserPromptSubmit = [...arr, { matcher: '*', hooks: [{ type: 'command', command: HOOK_CMD, timeout: 5 }] }];
   } else {
+    if (!arr.some(isOurs)) { console.log(dim('autopilot already off.')); return; }
     const kept = arr.filter(e => !isOurs(e));
     if (kept.length) settings.hooks.UserPromptSubmit = kept;
     else delete settings.hooks.UserPromptSubmit;
@@ -80,7 +87,9 @@ module.exports = async function hook(argv) {
   try {
     fs.mkdirSync(path.dirname(p), { recursive: true });
     if (fs.existsSync(p) && !fs.existsSync(`${p}.bak`)) fs.copyFileSync(p, `${p}.bak`); // keep the pristine original
-    fs.writeFileSync(p, JSON.stringify(settings, null, 2) + '\n');
+    // Removing our only setting? Don't leave a bare `{}` behind — drop the file.
+    if (sub === 'off' && !Object.keys(settings).length && fs.existsSync(p)) fs.rmSync(p, { force: true });
+    else fs.writeFileSync(p, JSON.stringify(settings, null, 2) + '\n');
   } catch (e) { console.error(`failed to write ${p}: ${e.message}`); process.exitCode = 1; return; }
 
   if (values.json) { console.log(JSON.stringify({ enabled: sub === 'on', settings: p })); return; }

package/src/commands/info.js

@@ -1,9 +1,27 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const { parse } = require('../args');
 const { loadData } = require('../data');
 const { buildIndices, suggestSkills } = require('../index-build');
-const { buildInfo, renderInfo } = require('../format');
+const { buildInfo, renderInfo, dim } = require('../format');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+
+// The authoritative one-liner: a skill's own SKILL.md `description:` frontmatter,
+// read locally when installed (offline). Catalog text is group-level; this is not.
+function localSkillDesc(skill) {
+  for (const s of fsu.scopesFor({})) {
+    try {
+      const md = fs.readFileSync(path.join(s.root, skill, 'SKILL.md'), 'utf8');
+      const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      const dm = fm && fm[1].match(/^description:\s*(.+)$/m);
+      if (dm) return dm[1].trim().replace(/^["']|["']$/g, '');
+    } catch { /* not installed in this scope */ }
+  }
+  return '';
+}
 
 const HELP = `usage: skills-atlas info <skill> [--all] [--json] [--zh]
 
@@ -18,6 +36,7 @@ module.exports = async function info(argv) {
   const name = positionals[0];
   if (!name) {
     console.error('usage: skills-atlas info <skill>');
+    console.error(dim('find a skill name first: skills-atlas search <keyword>'));
     process.exitCode = 1;
     return;
   }
@@ -43,5 +62,8 @@ module.exports = async function info(argv) {
     console.log(JSON.stringify(infoObj, null, 2));
     return;
   }
-  console.log(renderInfo(infoObj, { en: !values.zh, all: values.all }));
+  const installed = [];
+  for (const s of fsu.scopesFor({})) if (manifest.list(s.root).some(e => e.skill === infoObj.skill)) installed.push(s.name);
+  const skillDesc = installed.length ? localSkillDesc(infoObj.skill) : '';
+  console.log(renderInfo(infoObj, { en: !values.zh, all: values.all, installed, skillDesc }));
 };

package/src/commands/install.js

@@ -25,6 +25,7 @@ options:
   -y, --yes          non-interactive (auto-pick top source, assume yes)
       --chain        install the whole ⛓ workflow this skill belongs to
       --dry-run      show what would download, write nothing
+      --verbose      with \`use\`: also print the full SKILL.md to the terminal
       --json         machine-readable output
 
 Downloads the repo archive (no GitHub API rate limit). Only if that fetch fails
@@ -86,12 +87,13 @@ async function installChain({ row, vendor, src, targetRoot, values }) {
 
 module.exports = async function install(argv) {
   const { values, positionals } = parse(argv,
-    ['global', 'project', 'source', 'force', 'yes', 'chain', 'inline', 'dry-run', 'json']);
+    ['global', 'project', 'source', 'force', 'yes', 'chain', 'inline', 'dry-run', 'verbose', 'json']);
   if (values.help) { console.log(HELP); return; }
 
   const name = positionals[0];
   if (!name) {
     console.error('usage: skills-atlas install <skill> [--global|--project] [--source <id>] [--force] [--yes]');
+    console.error(dim('find a skill first: skills-atlas search <keyword>'));
     process.exitCode = 1;
     return;
   }
@@ -126,23 +128,26 @@ module.exports = async function install(argv) {
       `${c.source.name}  ${stars(c.source.stars)}  ${c.source.type || ''}  ${(c.source.install && c.source.install.command) || ''}`);
     const i = await choose(`'${name}' is available from ${candidates.length} sources:`, labels);
     if (i < 0) {
-      console.error(`multiple sources for '${name}'. re-run with --source <id> or --yes.`);
-      console.error(`sources: ${candidates.map(c => c.source.name).join(', ')}`);
+      // Non-interactive without a pick: show each source so the user can decide
+      // (stars / type / install command), instead of just listing bare names.
+      console.error(`'${name}' has ${candidates.length} sources — pick one with --source <id>, or --yes to auto-pick the top:`);
+      candidates.forEach(c => console.error(dim(
+        `  ${c.source.name}  ${stars(c.source.stars)}  ${c.source.type || ''}` +
+        `${(c.source.install && c.source.install.command) ? '  → ' + c.source.install.command : ''}`)));
       process.exitCode = 2;
       return;
     }
     chosen = candidates[i];
   }
 
-  // Heads-up when --yes auto-picked among semantically different groups.
-  if (values.yes && candidates.length > 1) {
-    const groups = [...new Set(candidates.map(c => c.row && c.row.group).filter(Boolean))];
-    if (groups.length > 1) {
-      const picked = chosen.row && chosen.row.group;
-      const otherGroups = groups.filter(g => g !== picked).join('; ');
-      const st = stars(chosen.source.stars);
-      console.error(dim(`note: '${name}' exists in ${groups.length} groups; auto-picked ${chosen.source.name}${st ? ' ' + st : ''} (${picked || '?'}). also in: ${otherGroups} — use --source to choose.`));
-    }
+  // Heads-up whenever --yes auto-picked among several sources — say which one and
+  // what else was available, so a silent pick of a lower-star (but installable)
+  // source over a higher-star whole-repo one is never a surprise.
+  if (values.yes && candidates.length > 1 && !values.json) {
+    const st = stars(chosen.source.stars);
+    const grp = chosen.row && chosen.row.group;
+    const others = candidates.filter(c => c !== chosen).map(c => c.source.name).join(', ');
+    console.error(dim(`note: '${name}' has ${candidates.length} sources; auto-picked ${chosen.source.name}${st ? ' ' + st : ''}${grp ? ` (${grp})` : ''}. also from: ${others} — use --source <id> to choose.`));
   }
 
   const v = chosen.vendor || {};
@@ -179,6 +184,9 @@ module.exports = async function install(argv) {
   }
 
   const targetRoot = fsu.installTargetDir({ global: resolveGlobal(values) });
+  // Global installs read best as ~/…; a --project path is shorter and clearer as a
+  // relative ./.claude/skills/<skill> than a long absolute path.
+  const showPath = pth => resolveGlobal(values) ? fsu.tildify(pth) : './' + path.relative(process.cwd(), pth);
   const isChain = Boolean(chosen.row && chosen.row.chain && (chosen.row.skills || []).length >= 2);
 
   // --- chain: install the whole workflow ---
@@ -228,7 +236,7 @@ module.exports = async function install(argv) {
       }));
       return;
     }
-    console.log(`would install ${listing.files.length} file(s) to ${fsu.tildify(dest)} (branch ${listing.branchUsed}):`);
+    console.log(`would install ${listing.files.length} file(s) to ${showPath(dest)} (branch ${listing.branchUsed}):`);
     listing.files.forEach(f => console.log(`  ${f.rel}`));
     if (listing.note) console.log(dim('  ' + listing.note));
     console.log(dim('  (real install fetches the repo archive — no GitHub API rate limit)'));
@@ -255,7 +263,7 @@ module.exports = async function install(argv) {
     return;
   }
 
-  console.log(`\n${green('✓')} installed ${bold(skill)} → ${fsu.tildify(result.dest)}  ${dim(`(${result.fileCount} file(s) from ${src.name}@${result.branchUsed})`)}`);
+  console.log(`\n${green('✓')} installed ${bold(skill)} → ${showPath(result.dest)}  ${dim(`(${result.fileCount} file(s) from ${src.name}@${result.branchUsed})`)}`);
   if (result.note) console.log(dim('  ' + result.note));
   console.log(dim(`  source: ${src.name}@${result.branchUsed} — branch HEAD, not a pinned commit; review before use`));
   if (result.scripts.length) {
@@ -274,13 +282,19 @@ module.exports = async function install(argv) {
 
   if (values.inline) {
     const body = readSkillMd(result.dest);
-    if (body) {
+    const mdPath = showPath(path.join(result.dest, 'SKILL.md'));
+    // Claude (and any piped caller) needs the full SKILL.md inline to apply the
+    // skill right now; a human at a terminal just needs the digest — the file is
+    // on disk and auto-loads, so dumping ~200 lines would only bury the next step.
+    const full = body && (values.verbose || !process.stdout.isTTY);
+    if (full) {
       console.log('\n' + dim('─── SKILL.md — the skill\'s own instructions; apply them to the task now ───'));
       console.log(body.trim());
       console.log(dim('─── end SKILL.md ───'));
     }
-    console.log(`\n${green('✓')} ${bold(skill)} is now active — use the instructions above for the task at hand.`);
-    console.log(dim(`  installed at ${fsu.tildify(result.dest)} (auto-loads in new sessions) · what it does: skills-atlas info ${skill} · remove: skills-atlas remove ${skill}`));
+    console.log(`\n${green('✓')} ${bold(skill)} is now active — ${full ? 'use the instructions above' : 'follow its SKILL.md'} for the task at hand.`);
+    console.log(dim(`  installed at ${showPath(result.dest)} (auto-loads in new sessions) · what it does: skills-atlas info ${skill} · remove: skills-atlas remove ${skill}`));
+    if (body && !full) console.log(dim(`  full instructions: ${mdPath}  (or re-run with --verbose)`));
   } else {
     console.log(`\n${bold(skill)} is installed but not loaded yet. To use it:`);
     console.log(dim(`  • now, in this session:  skills-atlas use ${skill}`));

package/src/commands/remove.js

@@ -19,8 +19,15 @@ module.exports = async function remove(argv) {
   const dest = path.join(root, name);
   const tracked = manifest.read(root).skills[name];
 
+  // Is the skill also present in the OTHER scope? (remove only touches one scope.)
+  const otherRoot = fsu.installTargetDir({ global: !global });
+  const otherFlag = global ? '--project' : '--global';
+  const otherHas = otherRoot !== root
+    && (fsu.dirExists(path.join(otherRoot, name)) || !!manifest.read(otherRoot).skills[name]);
+
   if (!fsu.dirExists(dest) && !tracked) {
     console.error(`'${name}' is not installed (${global ? 'global' : 'project'}).`);
+    if (otherHas) console.error(dim(`it is installed in the ${global ? 'project' : 'global'} scope — try: skills-atlas remove ${name} ${otherFlag}`));
     process.exitCode = 1;
     return;
   }
@@ -35,4 +42,5 @@ module.exports = async function remove(argv) {
 
   if (values.json) { console.log(JSON.stringify({ removed: name, dest })); return; }
   console.log(`${green('✓')} removed ${name}  ${dim(fsu.tildify(dest))}`);
+  if (otherHas) console.log(dim(`note: '${name}' is still installed in the ${global ? 'project' : 'global'} scope — remove that too: skills-atlas remove ${name} ${otherFlag}`));
 };

package/src/commands/search.js

@@ -5,6 +5,8 @@ const { loadData } = require('../data');
 const { buildIndices, suggestSkills } = require('../index-build');
 const { runSearch } = require('../search-core');
 const { renderRow, dim } = require('../format');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
 
 const HELP = `usage: skills-atlas search <query...> [filters]
 
@@ -12,7 +14,8 @@ Matches by words, not whole-string: multiple keywords and loose phrases work
 (e.g. "pdf 翻译", "translate a whole pdf"). Ranked by how much of the query hits.
 
 filters:
-  -c, --category <s>   match a top-level category (loose, zh or en)
+  -c, --category <s>   match a top-level category (loose; zh or en; e.g. -c marketing).
+                       run \`skills-atlas categories\` for the exact names
   -p, --persona <s>    match a persona — English or Chinese, e.g.
                        engineering, pm, design, marketing, research, ops,
                        founder, job-seeking, general (工程/PM/设计/营销/...)
@@ -62,7 +65,10 @@ module.exports = async function search(argv) {
   const shown = rows.slice(0, limit);
 
   if (values.json) {
-    console.log(JSON.stringify(shown.map(jsonRow), null, 2));
+    console.log(JSON.stringify({
+      query, total: rows.length, shown: shown.length, weak,
+      results: shown.map(jsonRow),
+    }, null, 2));
     return;
   }
 
@@ -73,15 +79,20 @@ module.exports = async function search(argv) {
       const { skillIndex } = buildIndices(data);
       const sugg = suggestSkills(skillIndex, query);
       if (sugg.length) console.log(dim(`did you mean: ${sugg.join(', ')}`));
-      console.log(dim('try fewer / different words, or `skills-atlas categories` to browse.'));
     }
+    if (values.category) console.log(dim(`if -c "${values.category}" isn't matching, run \`skills-atlas categories\` for the exact names.`));
+    console.log(dim('try fewer / different words, or `skills-atlas categories` to browse.'));
     return;
   }
 
   if (weak) {
-    console.log(dim('\n⚠ weak matches — none of the results cover your whole query; try different words.'));
+    console.log(dim('\n⚠ partial match — results may cover only part of your query; the top ones can still help, or try different words.'));
   }
-  shown.forEach(r => console.log(renderRow(r, { en })));
-  const more = rows.length > limit ? `, showing ${limit}` : '';
-  console.log(`\n${rows.length} match(es)${more}.`);
+  const installedSet = new Set();
+  for (const s of fsu.scopesFor({})) for (const e of manifest.list(s.root)) installedSet.add(e.skill);
+  shown.forEach(r => console.log(renderRow(r, { en, installed: installedSet, vendors: data.vendors })));
+  const truncated = rows.length > limit;
+  console.log(`\n${rows.length} match(es)${truncated ? `, showing ${limit}` : ''}.`);
+  if (truncated) console.log(dim(`see the rest with --limit ${rows.length}${values.category ? '' : ', or narrow with -c <category>'}.`));
+  console.log(dim('next: skills-atlas info <skill> to learn more, or skills-atlas use <skill> to install it.'));
 };

package/src/commands/update.js

@@ -28,6 +28,7 @@ module.exports = async function update(argv) {
     }
   } catch (e) {
     console.error(`update failed: ${e.message}`);
+    console.error('your existing catalog is unchanged and still usable offline.');
     process.exitCode = 1;
   }
 };

package/src/commands/upgrade.js

@@ -32,8 +32,15 @@ module.exports = async function upgrade(argv) {
     for (const n of names) targets.push({ scope: s, name: n, entry: m.skills[n] });
   }
   if (!targets.length) {
-    if (values.json) { console.log('[]'); return; }
-    console.log(positionals[0] ? `'${positionals[0]}' is not installed by skills-atlas.` : 'nothing installed to upgrade.');
+    if (values.json) { console.log('[]'); if (positionals[0]) process.exitCode = 1; return; }
+    if (positionals[0]) {
+      // A named skill that isn't installed is a user error → non-zero, like `remove`.
+      console.log(`'${positionals[0]}' is not installed by skills-atlas.`);
+      console.log(dim('see what is: skills-atlas installed'));
+      process.exitCode = 1;
+    } else {
+      console.log('nothing installed to upgrade.');
+    }
     return;
   }
 

package/src/data.js

@@ -31,8 +31,17 @@ function tryReadJSON(p) {
   }
 }
 
+// Structural validation, not just "has the two top keys". The catalog is iterated
+// as sections[].subsections[].rows[] everywhere (counts/merge/search), so a source
+// missing that shape (e.g. an old `subgroups`/`groups` schema) must be rejected
+// HERE — both to fail `registry add` cleanly and to keep a stale bad cache from
+// being merged as an overlay and crashing every downstream command.
 function isValid(d) {
-  return d && Array.isArray(d.sections) && d.vendors && typeof d.vendors === 'object';
+  return !!d
+    && Array.isArray(d.sections)
+    && d.sections.every(s => s && Array.isArray(s.subsections)
+      && s.subsections.every(ss => ss && Array.isArray(ss.rows)))
+    && !!d.vendors && typeof d.vendors === 'object';
 }
 
 function counts(d) {
@@ -63,7 +72,10 @@ function loadBundled() {
     'or run `skills-atlas update` to fetch the catalog.');
 }
 
+const nudgeFile = () => path.join(cacheDir(), 'nudge.json');
+
 // One-line stderr nudge when the catalog is the bundled snapshot or a stale cache.
+// Throttled to once per day so it informs without nagging on every command.
 function maybeStaleNudge(fromCache) {
   const meta = tryReadJSON(metaFile());
   let stale = true;
@@ -71,9 +83,14 @@ function maybeStaleNudge(fromCache) {
     const ageDays = (Date.now() - Date.parse(meta.fetchedAt)) / 86400000;
     stale = !(ageDays >= 0 && ageDays < STALE_DAYS);
   }
-  if (stale) {
-    process.stderr.write("tip: run 'skills-atlas update' to refresh the catalog\n");
-  }
+  if (!stale) return;
+  try {
+    const n = tryReadJSON(nudgeFile());
+    if (n && n.at && (Date.now() - Date.parse(n.at)) < 86400000) return; // shown within the day
+    fs.mkdirSync(cacheDir(), { recursive: true });
+    fs.writeFileSync(nudgeFile(), JSON.stringify({ at: new Date().toISOString() }));
+  } catch { /* throttle I/O is best-effort */ }
+  process.stderr.write("tip: run 'skills-atlas update' to refresh the catalog\n");
 }
 
 function loadData({ quiet = false } = {}) {
@@ -188,4 +205,4 @@ async function refreshSources() {
   return out;
 }
 
-module.exports = { loadData, refreshData, fetchSource, refreshSources, counts, cacheDir, PUBLIC_URL };
+module.exports = { loadData, refreshData, fetchSource, refreshSources, counts, isValid, cacheDir, PUBLIC_URL };

package/src/format.js

@@ -19,6 +19,17 @@ function stars(n) {
   return `★${n}`;
 }
 
+// Repo freshness from a source's `last_commit` ("2026-05-28"). Returns null if
+// absent/unparseable. `stale` flags a repo untouched for over a year — so a popular
+// but abandoned source no longer looks identical to an actively maintained one.
+function recency(lastCommit, now = Date.now()) {
+  if (!lastCommit) return null;
+  const t = Date.parse(lastCommit);
+  if (!Number.isFinite(t)) return null;
+  const days = Math.floor((now - t) / 86400000);
+  return { date: String(lastCommit).slice(0, 10), days, stale: days > 365 };
+}
+
 // A `git clone <repo> ~/.claude/skills/skills` alt double-nests a multi-skill
 // monorepo (skills end up at .claude/skills/skills/<name>/) and won't load —
 // drop that foot-gun; the `npx skills add` command is the correct path.
@@ -34,18 +45,33 @@ function text(obj, key, en) {
   return en ? (obj[key + '_en'] || obj[key] || '') : (obj[key] || obj[key + '_en'] || '');
 }
 
-// One search/list result line block.
-function renderRow(r, { en = false } = {}) {
+// One search/list result line block. `installed` (a Set of skill names) marks what
+// you already have; `vendors` lets the source line say whether install is a clean
+// single-skill folder or a whole-repo command.
+function renderRow(r, { en = false, installed = null, vendors = null } = {}) {
   const chain = r.chain ? cyan('⛓ ') : '';
   const cat = en ? (r._catEn || r._cat) : r._cat;
   const lines = [`\n${chain}${bold(text(r, 'group', en))}   ${dim('[' + cat + ']')}`];
   const uc = text(r, 'use_case', en);
   if (uc) lines.push(`  💡 ${uc}`);
-  lines.push(`  ${dim('skills:')} ${green(r.skills.join(', '))}`);
+  const SK_MAX = 8;
+  const sk = r.skills || [];
+  const tick = s => (installed && installed.has(s)) ? green(s + ' ✓') : green(s);
+  const skStr = sk.length > SK_MAX
+    ? sk.slice(0, SK_MAX).map(tick).join(dim(', ')) + dim(` +${sk.length - SK_MAX} more`)
+    : sk.map(tick).join(dim(', '));
+  lines.push(`  ${dim('skills:')} ${skStr}`);
   const best = [...(r.sources || [])].sort((a, b) => (b.stars || 0) - (a.stars || 0))[0];
   if (best) {
+    const rec = recency(best.last_commit);
+    const recStr = rec ? `  updated ${rec.date}${rec.stale ? ' ⚠' : ''}` : '';
+    let kind = '';
+    if (vendors) {
+      const v = vendors[best.name];
+      kind = (v && skillDocPath(v, sk[0])) ? '  [single-skill]' : '  [whole-repo]';
+    }
     const inst = best.install && best.install.command ? ` — ${best.install.command}` : '';
-    lines.push(`  ${dim('via')} ${best.name} ${yellow(stars(best.stars))}${dim(inst)}`);
+    lines.push(`  ${dim('via')} ${best.name} ${yellow(stars(best.stars))}${dim(recStr)}${dim(kind)}${dim(inst)}`);
   }
   return lines.join('\n');
 }
@@ -84,6 +110,7 @@ function groupOf(r, skillName, vendors) {
         id: s.name,
         url: s.url,
         stars: s.stars,
+        last_commit: s.last_commit || v.last_commit || null,
         license: (v.skill_licenses && v.skill_licenses[skillName]) || s.license || null,
         type: s.type,
         path: docPath || null,
@@ -123,15 +150,40 @@ function infoForRow(skillName, row, vendors) {
   return { skill: skillName, found: true, groups: [groupOf(row, skillName, vendors)] };
 }
 
-function renderInfo(info, { en = false, all = false } = {}) {
+// Multi-skill groups share one description that often enumerates each skill as
+// "<vendor> <skill> (<detail>) + …". Pull out the segment for THIS skill so info
+// pinpoints what it does, not just the whole group. Conservative: only fire when
+// the skill matches exactly one segment (otherwise we'd guess wrong).
+function perSkillBlurb(skill, desc) {
+  if (!skill || !desc) return '';
+  const segs = String(desc).split(' + ');
+  if (segs.length < 2) return '';
+  const re = new RegExp('\\b' + String(skill).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'i');
+  const hits = segs.filter(s => re.test(s));
+  if (hits.length !== 1) return '';
+  const seg = hits[0].trim();
+  return /[(（]/.test(seg) ? seg : '';   // only worth showing if it carries a detail
+}
+
+// `skillDesc` is the authoritative one-liner from the skill's own SKILL.md (read
+// locally when installed); it wins over the heuristic catalog-segment extraction.
+function renderInfo(info, { en = false, all = false, installed = null, skillDesc = '' } = {}) {
   const pick = (zh, e) => (en ? (e || zh) : (zh || e)) || '';
   const out = [];
-  out.push(`\n${bold(green(info.skill))}${info.groups.some(g => g.chain) ? ' ' + cyan('⛓') : ''}`);
+  const instTag = installed && installed.length
+    ? ` ${green('✓ installed')} ${dim('[' + installed.join('+') + ']')}` : '';
+  out.push(`\n${bold(green(info.skill))}${info.groups.some(g => g.chain) ? ' ' + cyan('⛓') : ''}${instTag}`);
   const shown = all ? info.groups : info.groups.slice(0, 1);
+  let firstGroup = true;
   for (const g of shown) {
     out.push(`  ${dim('group:')} ${pick(g.group, g.group_en)}  ${dim('[' + pick(g.category, g.category_en) + ']')}`);
     const desc = pick(g.description, g.description_en);
-    if (desc) out.push(`  ${desc}`);
+    const blurb = (firstGroup && skillDesc) ? skillDesc : perSkillBlurb(info.skill, desc);
+    firstGroup = false;
+    const distinguished = blurb && blurb !== desc;
+    if (distinguished) out.push(`  ${dim('this skill:')} ${blurb}`);
+    // Only call it "group does:" when a per-skill line is shown above it to contrast.
+    if (desc) out.push(distinguished ? `  ${dim('group does:')} ${desc}` : `  ${desc}`);
     const uc = pick(g.use_case, g.use_case_en);
     if (uc) out.push(`  ${dim('use case:')} ${uc}`);
     const wt = pick(g.when_to_use, g.when_to_use_en);
@@ -141,7 +193,9 @@ function renderInfo(info, { en = false, all = false } = {}) {
     }
     out.push(`  ${dim('sources:')}`);
     for (const s of g.sources) {
-      out.push(`    • ${bold(s.id)} ${yellow(stars(s.stars))} ${dim(s.type || '')} ${s.license ? dim('(' + s.license + ')') : ''}`);
+      const rec = recency(s.last_commit);
+      const recStr = rec ? `  ${dim('updated ' + rec.date)}${rec.stale ? ' ' + yellow('⚠ stale') : ''}` : '';
+      out.push(`    • ${bold(s.id)} ${yellow(stars(s.stars))} ${dim(s.type || '')} ${s.license ? dim('(' + s.license + ')') : ''}${recStr}`);
       out.push(`      ${dim(s.url)}`);
       out.push(`      ${dim('path:')} ${s.path || dim('(whole-repo install — no per-skill folder)')}`);
       if (s.install && s.install.command) {
@@ -161,6 +215,6 @@ function renderInfo(info, { en = false, all = false } = {}) {
 }
 
 module.exports = {
-  bold, dim, green, cyan, yellow, stars, safeAlt, text, renderRow,
-  buildInfo, infoForRow, renderInfo,
+  bold, dim, green, cyan, yellow, stars, recency, perSkillBlurb, safeAlt, text, renderRow,
+  buildInfo, infoForRow, renderInfo, PERSONA_EN,
 };

package/src/mcp.js

@@ -8,7 +8,7 @@ const path = require('path');
 const { loadData } = require('./data');
 const { buildIndices, vendorsFor, skillDocPath, suggestSkills } = require('./index-build');
 const { runSearch } = require('./search-core');
-const { buildInfo } = require('./format');
+const { buildInfo, PERSONA_EN } = require('./format');
 const fsu = require('./fsutil');
 const { installFolder } = require('./installer');
 
@@ -29,7 +29,8 @@ function fmtSearch(data, { query, limit }) {
       (uc ? `\n  ${uc}` : '') +
       (src.name ? `\n  via ${src.name} ★${src.stars || 0}${cmd ? ` — ${cmd}` : ''}` : '');
   });
-  return `${rows.length} result(s) for "${query}" (showing ${n}):\n\n${out.join('\n\n')}`;
+  const more = n < rows.length ? `\n\n(showing ${n} of ${rows.length}; pass limit:${rows.length} to see all)` : '';
+  return `${rows.length} result(s) for "${query}" (showing ${n}):\n\n${out.join('\n\n')}${more}`;
 }
 
 function fmtInfo(data, { skill }) {
@@ -44,7 +45,7 @@ function fmtInfo(data, { skill }) {
   const desc = g.description_en || g.description; if (desc) lines.push(desc);
   const uc = g.use_case_en || g.use_case; if (uc) lines.push(`use case: ${uc}`);
   const wt = g.when_to_use_en || g.when_to_use; if (wt) lines.push(`when: ${wt}`);
-  if (g.personas && g.personas.length) lines.push(`personas: ${g.personas.join(', ')}`);
+  if (g.personas && g.personas.length) lines.push(`personas: ${g.personas.map(p => PERSONA_EN[p] || p).join(', ')}`);
   lines.push('sources:');
   for (const s of g.sources) {
     lines.push(`  - ${s.id} ★${s.stars || 0}${s.license ? ` (${s.license})` : ''}  ${s.path || '(whole-repo install)'}`);
@@ -107,8 +108,8 @@ async function doInstall(data, { skill, scope, source, dry_run }) {
 
 function toolDefs() {
   return [
-    { name: 'search_skills', description: 'Search the Skills Atlas catalog of AI agent skills by keyword or short task description.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'keywords or a short task description' }, limit: { type: 'integer', minimum: 1, description: 'max results (default 10)' } }, required: ['query'] } },
-    { name: 'skill_info', description: 'Show what a catalog skill does, when to use it, its sources, and how to install it.', inputSchema: { type: 'object', properties: { skill: { type: 'string' } }, required: ['skill'] } },
+    { name: 'search_skills', description: 'Search the Skills Atlas catalog of AI agent skills by keyword or short task description. To install a result, call install_skill with the skill name — do not run the npx/install command shown in the results (that is the source reference, often a whole-repo install).', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'keywords or a short task description' }, limit: { type: 'integer', minimum: 1, description: 'max results (default 10)' } }, required: ['query'] } },
+    { name: 'skill_info', description: 'Show what a catalog skill does, when to use it, its sources, and how to install it.', inputSchema: { type: 'object', properties: { skill: { type: 'string', description: 'exact skill name (e.g. brainstorming); fuzzy matching and typo correction are applied' } }, required: ['skill'] } },
     { name: 'install_skill', description: 'Install a skill from the catalog into .claude/skills/.', inputSchema: { type: 'object', properties: { skill: { type: 'string' }, scope: { type: 'string', enum: ['global', 'project'], description: 'default global (~/.claude/skills)' }, source: { type: 'string', description: 'pick a source when several provide the skill' }, dry_run: { type: 'boolean' } }, required: ['skill'] } },
     { name: 'list_categories', description: "List the catalog's top-level categories, or the skill groups within one.", inputSchema: { type: 'object', properties: { category: { type: 'string', description: 'optional — drill into one category' } } } },
   ];
@@ -119,6 +120,8 @@ async function callTool(name, args, data) {
   switch (name) {
     case 'search_skills':
       if (!args.query) return { text: 'missing required "query".', isError: true };
+      if (args.limit !== undefined && (!Number.isInteger(args.limit) || args.limit < 1))
+        return { text: `invalid "limit": ${JSON.stringify(args.limit)} (must be a positive integer).`, isError: true };
       return { text: fmtSearch(data, args) };
     case 'skill_info':
       if (!args.skill) return { text: 'missing required "skill".', isError: true };
@@ -138,21 +141,26 @@ async function handle(req, { data }) {
   const ok = result => ({ jsonrpc: '2.0', id, result });
   const err = (code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
   if (!req || req.jsonrpc !== '2.0') return id === undefined ? null : err(-32600, 'Invalid Request');
-  switch (req.method) {
-    case 'initialize':
-      return ok({ protocolVersion: (req.params && req.params.protocolVersion) || PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'skills-atlas', version: VERSION } });
-    case 'notifications/initialized':
-    case 'initialized':
-      return null;
-    case 'tools/list':
-      return ok({ tools: toolDefs() });
-    case 'tools/call': {
-      const p = req.params || {};
-      const r = await callTool(p.name, p.arguments, data);
-      return ok({ content: [{ type: 'text', text: r.text }], isError: Boolean(r.isError) });
+  try {
+    switch (req.method) {
+      case 'initialize':
+        return ok({ protocolVersion: (req.params && req.params.protocolVersion) || PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'skills-atlas', version: VERSION } });
+      case 'notifications/initialized':
+      case 'initialized':
+        return null;
+      case 'tools/list':
+        return ok({ tools: toolDefs() });
+      case 'tools/call': {
+        const p = req.params || {};
+        const r = await callTool(p.name, p.arguments, data);
+        return ok({ content: [{ type: 'text', text: r.text }], isError: Boolean(r.isError) });
+      }
+      default:
+        return id === undefined ? null : err(-32601, 'Method not found');
     }
-    default:
-      return id === undefined ? null : err(-32601, 'Method not found');
+  } catch (e) {
+    // A request with an id MUST get a response — never leave the client hanging.
+    return id === undefined ? null : err(-32603, (e && e.message) || 'Internal error');
   }
 }
 

package/src/search-core.js

@@ -23,8 +23,16 @@ const STOP = new Set([
   '在', '是', '就', '也', '都', '还', '让', '跟', '对', '向', '我们', '帮我', '我想',
 ]);
 
+// Leading interrogative / filler phrases ("如何…", "how do i…", "i want to…") add
+// noise tokens — including a bridging CJK bigram ("如何重构" → keeps "何重") — that
+// dilute coverage and wrongly flag a good query as weak. Strip them up front.
+const LEAD_FILLER_EN = /^(?:\s*(?:how\s+(?:do|can|should)\s+(?:i|we|you)|how\s+to|i\s+(?:want|need|wanna)\s+to|i\s+would\s+like\s+to|can\s+you|could\s+you|please|help\s+me|let'?s)\s+)+/;
+const LEAD_FILLER_ZH = /^(?:如何|怎么样|怎样|怎么|请问|帮我看看|帮我|我想要|我想|我要|我需要|麻烦)+/;
+const stripLeadingFillers = q => q.replace(LEAD_FILLER_EN, '').replace(LEAD_FILLER_ZH, '');
+
 // Split a (lowercased) query into search terms.
 function tokenize(query) {
+  query = stripLeadingFillers(query);
   const out = new Set();
   const re = /[a-z0-9]+|[一-鿿]+/g;
   let m;
@@ -249,12 +257,19 @@ function suggestCandidates(rows, prompt, { installed = new Set(), suggested = ne
   const push = (skill, row) => { if (!seen.has(skill)) { seen.add(skill); out.push({ skill, row }); } };
   for (const a of anchors) { if (out.length >= limit) break; push(a.skill, a.row); }
 
-  // 2. fill from the general ranked search (one primary skill per row)
+  // 2. fill remaining slots from the general ranked search — but only with rows
+  // that are actually on-topic (a name/group hit, or strong coverage). A lone
+  // description-word match must not pad the shortlist with off-topic skills
+  // (e.g. "product-marketing" riding into a "debug this crash" prompt).
   const { rows: ranked, weak } = runSearch(rows, { query: prompt });
   for (const r of ranked) {
     if (out.length >= limit) break;
     const s = (r.skills || []).find(x => !seen.has(x));
-    if (s) push(s, r);
+    if (!s) continue;
+    const f = buildFields(r);
+    const nameOrGroup = tokens.some(t => fieldHas(f.name, t) || fieldHas(f.group, t));
+    if (!nameOrGroup && scoreRow(r, tokens, lc(prompt)).coverage < 0.6) continue;
+    push(s, r);
   }
 
   // fire decision: only on a real name anchor — two contentful name words, OR one