skills-atlas-cli 0.7.0 → 0.8.2

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`
+npm install -g skills-atlas-cli      # adds the `skills-atlas` command (alias sa). Or run any command with `npx`.
 
-## How you'll use it
-
-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
@@ -153,7 +147,21 @@ just describe what you need, or use `/skills-atlas:skill-search`, `:skill-info`,
 /plugin install skills-atlas@skills-atlas
 ```
 
-## Autopilot (opt-in) — the right skill finds you
+## 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:
+
+```json
+{ "mcpServers": { "skills-atlas": { "command": "npx", "args": ["-y", "skills-atlas-cli", "mcp"] } } }
+```
+
+It exposes four tools: **search_skills**, **skill_info**, **install_skill**, and
+**list_categories**. Discover, inspect, install, and browse the catalog from
+anywhere.
+
+## Autopilot (opt-in): the right skill finds you
 
 ```bash
 skills-atlas hook on      # enable    (skills-atlas hook off / status)
@@ -161,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/bin/skills.js

@@ -16,12 +16,13 @@ const suggest = require('../src/commands/suggest');
 const hook = require('../src/commands/hook');
 const gaps = require('../src/commands/gaps');
 const update = require('../src/commands/update');
+const mcp = require('../src/commands/mcp');
 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, update, categories, list, registry };
+const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, update, categories, list, registry, mcp };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -52,6 +53,9 @@ catalog:
   list [category]    list skill groups (optionally within one category)
   registry           add/list/remove a private catalog source (org-internal skills)
 
+integrations:
+  mcp                run as an MCP server (search/info/install/categories for any MCP client)
+
 global flags: --zh (中文 output; English by default), --json (machine output), -h/--help
 docs: https://zita-go.github.io/Skills-Atlas/`;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "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

@@ -3,7 +3,7 @@
 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 HELP = `usage: skills-atlas info <skill> [--all] [--json] [--zh]
 
@@ -18,6 +18,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;
   }

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/mcp.js

@@ -0,0 +1,5 @@
+// `skills-atlas mcp` — start the stdio MCP server (blocks; speaks JSON-RPC 2.0 over
+// stdin/stdout for an MCP client to spawn). All logic lives in ../mcp.
+'use strict';
+
+module.exports = () => require('../mcp').start();

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

@@ -12,7 +12,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 +63,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 +77,18 @@ 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 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

@@ -41,7 +41,12 @@ function renderRow(r, { en = false } = {}) {
   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 skStr = sk.length > SK_MAX
+    ? green(sk.slice(0, SK_MAX).join(', ')) + dim(` +${sk.length - SK_MAX} more`)
+    : green(sk.join(', '));
+  lines.push(`  ${dim('skills:')} ${skStr}`);
   const best = [...(r.sources || [])].sort((a, b) => (b.stars || 0) - (a.stars || 0))[0];
   if (best) {
     const inst = best.install && best.install.command ? ` — ${best.install.command}` : '';
@@ -162,5 +167,5 @@ function renderInfo(info, { en = false, all = false } = {}) {
 
 module.exports = {
   bold, dim, green, cyan, yellow, stars, safeAlt, text, renderRow,
-  buildInfo, infoForRow, renderInfo,
+  buildInfo, infoForRow, renderInfo, PERSONA_EN,
 };

package/src/mcp.js

@@ -0,0 +1,190 @@
+// Hand-rolled, zero-dep MCP (Model Context Protocol) server exposing the catalog
+// over stdio (newline-delimited JSON-RPC 2.0). `handle()` is a pure dispatcher
+// (catalog injected) for tests; `start()` wires stdin/stdout. stdout carries ONLY
+// protocol JSON — never console.log here.
+'use strict';
+
+const path = require('path');
+const { loadData } = require('./data');
+const { buildIndices, vendorsFor, skillDocPath, suggestSkills } = require('./index-build');
+const { runSearch } = require('./search-core');
+const { buildInfo, PERSONA_EN } = require('./format');
+const fsu = require('./fsutil');
+const { installFolder } = require('./installer');
+
+const VERSION = require('../package.json').version;
+const PROTOCOL = '2025-06-18';
+
+// ---- tool result formatters (plain text, no ANSI) ----
+function fmtSearch(data, { query, limit }) {
+  const { flatRows } = buildIndices(data);
+  const { rows } = runSearch(flatRows, { query });
+  if (!rows.length) return `No skills match "${query}".`;
+  const n = Math.min(rows.length, (Number.isInteger(limit) && limit > 0) ? limit : 10);
+  const out = rows.slice(0, n).map(r => {
+    const src = [...(r.sources || [])].sort((a, b) => (b.stars || 0) - (a.stars || 0))[0] || {};
+    const uc = r.use_case_en || r.use_case || '';
+    const cmd = src.install && src.install.command ? src.install.command : '';
+    return `• ${(r.skills || []).join(', ')}  [${r.group_en || r.group}]` +
+      (uc ? `\n  ${uc}` : '') +
+      (src.name ? `\n  via ${src.name} ★${src.stars || 0}${cmd ? ` — ${cmd}` : ''}` : '');
+  });
+  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 }) {
+  const idx = buildIndices(data);
+  const info = buildInfo(skill, { skillIndex: idx.skillIndex, vendors: data.vendors });
+  if (!info.found) {
+    const sugg = suggestSkills(idx.skillIndex, skill);
+    return `Skill "${skill}" not found.${sugg.length ? ` Did you mean: ${sugg.join(', ')}.` : ''}`;
+  }
+  const g = info.groups[0];
+  const lines = [`${skill}  [${g.category_en || g.category}] — group: ${g.group_en || g.group}`];
+  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.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)'}`);
+    if (s.install && s.install.command) lines.push(`    install: ${s.install.command}`);
+  }
+  if (info.groups.length > 1) lines.push(`(+${info.groups.length - 1} other group(s) with a same-named skill)`);
+  return lines.join('\n');
+}
+
+function fmtCategories(data, { category }) {
+  if (!category) {
+    const out = data.sections.map(s => {
+      const groups = s.subsections.reduce((m, ss) => m + ss.rows.length, 0);
+      return `• ${s.title_en || s.title}  (${groups} groups)`;
+    });
+    return `Categories:\n${out.join('\n')}`;
+  }
+  const lc = String(category).toLowerCase();
+  const sec = data.sections.find(s =>
+    (s.title_en || '').toLowerCase().includes(lc) || (s.title || '').toLowerCase().includes(lc));
+  if (!sec) return `Category "${category}" not found. Run list_categories with no argument to see them.`;
+  const groups = sec.subsections.flatMap(ss => ss.rows.map(r => `  • ${r.group_en || r.group}  — ${(r.skills || []).join(', ')}`));
+  return `${sec.title_en || sec.title}:\n${groups.join('\n')}`;
+}
+
+async function doInstall(data, { skill, scope, source, dry_run }) {
+  const idx = buildIndices(data);
+  const candidates = vendorsFor(idx.skillIndex, skill);
+  if (!candidates.length) {
+    const sugg = suggestSkills(idx.skillIndex, skill);
+    return { text: `Skill "${skill}" not found.${sugg.length ? ` Did you mean: ${sugg.join(', ')}.` : ''}`, isError: true };
+  }
+  const chosen = source
+    ? candidates.find(c => c.source.name.toLowerCase() === String(source).toLowerCase())
+    : candidates[0];
+  if (!chosen) return { text: `Source "${source}" does not provide "${skill}". Available: ${candidates.map(c => c.source.name).join(', ')}.`, isError: true };
+  const v = chosen.vendor, src = chosen.source;
+  const name = chosen.skill || skill;
+  const docPath = skillDocPath(v, name);
+  if (!docPath) {
+    const cmd = (src.install || v.install || {}).command;
+    return { text: `"${skill}" from ${src.name} installs the whole repo, not a single folder.${cmd ? ` Run: ${cmd}` : ''}` };
+  }
+  const global = scope !== 'project';
+  const targetRoot = fsu.installTargetDir({ global });
+  const dest = path.join(targetRoot, name);
+  if (dry_run) return { text: `[dry run] would install "${skill}" from ${src.name} → ${fsu.tildify(dest)} (no files written).` };
+  try {
+    const r = await installFolder({
+      author: v.author || src.author, repo: v.repo || src.repo,
+      branch: v.default_branch || src.default_branch || 'main',
+      docPath, dest, targetRoot, skillName: name,
+      source: src.name, group: chosen.row && chosen.row.group, category: chosen.row && chosen.row._cat,
+    });
+    return { text: `Installed "${skill}" — ${r.fileCount} file(s) from ${src.name}@${r.branchUsed} → ${fsu.tildify(r.dest)}.${r.scripts.length ? ` Includes ${r.scripts.length} script file(s); review before use.` : ''}` };
+  } catch (e) {
+    return { text: `Install failed: ${e.message}`, isError: true };
+  }
+}
+
+function toolDefs() {
+  return [
+    { 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' } } } },
+  ];
+}
+
+async function callTool(name, args, data) {
+  args = args || {};
+  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 };
+      return { text: fmtInfo(data, args) };
+    case 'list_categories':
+      return { text: fmtCategories(data, args) };
+    case 'install_skill':
+      if (!args.skill) return { text: 'missing required "skill".', isError: true };
+      return await doInstall(data, args);
+    default:
+      return { text: `unknown tool: ${name}`, isError: true };
+  }
+}
+
+async function handle(req, { data }) {
+  const id = req && req.id;
+  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');
+  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');
+    }
+  } 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');
+  }
+}
+
+function start() {
+  let data;
+  try { data = loadData({ quiet: true }).data; }
+  catch (e) { process.stderr.write(`skills-atlas mcp: ${e.message}\n`); process.exit(1); return; }
+  let buf = '';
+  let queue = Promise.resolve();
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let req; try { req = JSON.parse(line); } catch { continue; }
+      queue = queue.then(async () => {
+        try { const res = await handle(req, { data }); if (res) process.stdout.write(JSON.stringify(res) + '\n'); }
+        catch { /* never crash the server */ }
+      });
+    }
+  });
+  process.stdin.on('end', () => { queue.then(() => process.exit(0)); });
+}
+
+module.exports = { handle, toolDefs, callTool, start };

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