@victortomaili/skill-cli 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -11,6 +11,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cursor adapter (`.cursor/rules` format) for `init -g` bootstrap.
 - Per-agent hook adapters for automatic `/X` triggering (push model).
 
+## [0.3.0] - 2026-07-07
+
+### Added
+- **`skill search` / `skill browse`** — interactive search & multi-install TUI (TTY only). Type a query → browse live `npx skills find` results → mark one or more with `space` → `enter` installs all marked → loops back so you can search again ("research" → pick → "deploy" → pick). `skill install` with no source also opens it on a terminal. Agents/CI (non-TTY) and explicit `skill install <source>` stay fully non-interactive.
+- **`@skill`-pinned sources** (`owner/repo@skill`) now install just that one skill instead of the whole repo (`--skill '*'` is dropped when the source is pinned).
+- **`skill` (no args) / `skill manager` / `skill ui`** — interactive skill-manager TUI (TTY only). Manage every installed skill from the keyboard: ↑↓ navigate · `space` toggle active in the current project · `d` delete (with confirm) · `enter` view the `SKILL.md` · `q` quit. Agents/CI (non-TTY) never enter it; `skill` with no args on a non-TTY still prints help. Toggle follows the allow/deny model (allow wins; a project deny overrides a global enable).
+- **Default skills — auto-load on session start.** New commands: `skill default <name> [-g]` / `skill undefault <name> [-g]` to mark/unmark, and `skill defaults` to list them (this is the command the agent runs on startup). The AGENTS.md bootstrap block now instructs the agent to run `skill defaults` then `skill cat <name>` for each. Defaults are a flag **independent** of enable/disable (a skill can be a default without being active), stored in `skill.config` `defaults:` (project) and `config.yaml` `defaults_global:` (global). Markable from the CLI, or in the manager via the `a` key (★ marker); `skill list` shows ★ too.
+
+### Fixed
+- `skill search` and the manager now exit on `ESC` (previously only Enter / Ctrl-C worked — the prebuilt `@inquirer` prompts ignore ESC). ESC aborts the active prompt via its `AbortSignal`; the terminal/raw-mode is restored on abort. The manager also quits on `ESC` from the main list.
+- **225 tests** (unit + CLI), network-free by default.
+
+## [0.2.0] - 2026-07-07
+
+### Added
+- `skill remove <name>... [-y]` (aliases `rm`, `uninstall`) — removes skill(s) from the store and cleans up the global enabled list + current project allow-list. Interactive `y/N` confirmation on a TTY (default **N** = keep); non-interactive for agents, CI, and pipes (non-TTY), or when `-y`/`--yes`/`-f`/`--force` is passed. Destination names are canonicalized via the store (case-insensitive; an unknown/`../x` name can't reach the store path). Duplicate and case-variant names are de-duplicated (one removal, accurate count).
+
 ## [0.1.1] - 2026-07-07
 
 ### Fixed
@@ -48,6 +65,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Windows `npx` spawn runs with `shell:false` + an args array and rejects sources
   containing shell metacharacters (`& | < > ^`).
 
-[Unreleased]: https://github.com/victortomaili/skill-cli/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/victortomaili/skill-cli/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/victortomaili/skill-cli/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/victortomaili/skill-cli/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/victortomaili/skill-cli/releases/tag/v0.1.0

package/README.md

@@ -6,7 +6,7 @@
 [![npm version](https://img.shields.io/npm/v/@victortomaili/skill-cli.svg)](https://www.npmjs.com/package/@victortomaili/skill-cli)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D22-green.svg)](https://nodejs.org)
-[![tests](https://img.shields.io/badge/tests-157%20passing-brightgreen.svg)](#development)
+[![tests](https://img.shields.io/badge/tests-225%20passing-brightgreen.svg)](#development)
 
 **skill-cli** is a cross-agent skill manager for AI coding agents (Claude Code,
 Codex, Cursor, Gemini, …). Skills live in a single global store — your agent
@@ -18,8 +18,10 @@ config file.
 - 🎛️ **Three-layer activation** — installed → enabled globally → enabled per project. `allow` always wins over `deny`.
 - 🔌 **Universal sources** — `owner/repo`, GitHub/GitLab URL, git URL, local path, npm package (via `npx skills`).
 - ⚡ **Pull-based** — agents pull skill content into context on demand via `skill trigger /X`. No hooks required.
+- 🔍 **Interactive TUIs** — `skill search` to discover & multi-install from the skills registry; `skill` (no args) to manage every installed skill with the keyboard. TTY-only; agents & CI stay non-interactive.
+- ⭐ **Default skills** — mark skills to auto-load on every agent session start.
 - 🖥️ **Cross-platform** — Windows, macOS, Linux (handles the Windows `npx` spawn quirk for you).
-- 🧪 **Well tested** — 157 unit + CLI tests, network-free by default.
+- 🧪 **Well tested** — 225 unit + CLI tests, network-free by default.
 
 ## ⭐ Found this useful?
 
@@ -40,10 +42,11 @@ Requires Node.js 22+.
 # 1) one-time global setup (creates the store + bootstraps detected agents)
 skill init -g
 
-# 2) install a skill from any source
+# 2) install a skill from any source (or `skill search` to browse interactively)
 skill install owner/repo
 
-# 3) use it — type /<trigger> in your agent, or load directly
+# 3) manage everything with the keyboard (terminal only)
+skill              # ↑↓ move · space toggle · a default · d delete · enter view
 skill list
 skill cat <name>
 ```
@@ -55,9 +58,9 @@ That's it. Your agent now knows: *when the user types `/X`, run `skill trigger X
 ```
 ~/.skill-cli/
   store/<skill>/SKILL.md     ← one canonical store (skills live here)
-  config.yaml                ← global config (enabled_global)
+  config.yaml                ← global config (enabled_global, defaults_global)
 
-<project>/skill.config       ← per-project activation (inherit / deny / allow)
+<project>/skill.config       ← per-project activation + defaults (inherit / deny / allow / defaults)
 ~/.claude/CLAUDE.md          ← bootstrap block injected by `skill init -g`
 ~/.codex/AGENTS.md             (idempotent — preserves your existing content)
 ~/.gemini/GEMINI.md
@@ -73,15 +76,21 @@ short bootstrap block telling it to run `skill` on `/X`.
 | `skill init -g` | Global setup: create store + inject bootstrap into agent files |
 | `skill init` | Create a `skill.config` for the current project |
 | `skill install <source>` | Fetch skill(s) to the store (agent dirs untouched) |
+| `skill search` | Interactive search & multi-install from the skills registry (TTY) |
+| `skill` / `skill manager` | Interactive manager: toggle, default, delete, view (TTY) |
 | `skill enable <name> [-g]` | Enable in project, or globally with `-g` |
 | `skill disable <name> [-g]` | Disable |
-| `skill list` | Show installed + active skills (cwd-aware) |
+| `skill default <name> [-g]` | Mark a skill to auto-load on session start |
+| `skill undefault <name> [-g]` | Remove the auto-load flag |
+| `skill defaults` | List default skills (the command your agent runs on start) |
+| `skill list` | Show installed + active skills (cwd-aware, ★ = default) |
 | `skill show <name>` | Skill metadata (path, triggers, version) |
 | `skill cat <name>` | Dump skill content into context |
-| `skill trigger <keyword>` | `/X` trigger: single→content, multi→candidates, none→info |
+| `skill trigger <keyword\|name>` | `/X` trigger or skill name → content (single), candidates (multi) |
 | `skill update [name…\|--all]` | Re-fetch from source, update changed skills |
+| `skill remove <name> [-y]` | Remove from store (prompts on TTY; agents / CI / `-y` skip) |
 
-Aliases: `ls` (list), `add` (install), `info` (show).
+Aliases: `ls` (list), `add` (install), `info` (show), `rm`/`uninstall` (remove), `browse` (search), `ui` (manager), `def` (default), `undef` (undefault).
 
 ## Install sources
 
@@ -138,11 +147,47 @@ allow: [react-best-practices]  # then open them one by one
 > `allow` always wins over `deny`, so `deny: ["*"]` + `allow: [X]` = "only X".
 > Matching is case-insensitive throughout.
 
+## Interactive mode (terminal only)
+
+When run in a real terminal, skill-cli offers two keyboard UIs. **Agents and CI
+never enter them** (a non-TTY stdin is detected) — they use the plain commands.
+
+### `skill` — manage installed skills
+
+Opens a full-screen manager over your store:
+
+| Key | Action |
+|---|---|
+| `↑` / `↓` | move |
+| `space` | toggle active in the current project |
+| `a` | toggle the default (auto-load) flag |
+| `d` | delete (asks `y/N`) |
+| `enter` | view the `SKILL.md` |
+| `q` / `esc` | quit |
+
+### `skill search` — discover & install
+
+Type a query → browse live results from the [skills registry](https://skills.sh)
+(`npx skills find`) → mark one or more with `space` → `enter` installs all marked
+→ loops back so you can search again. `esc` or an empty query quits. `skill install`
+with no source also opens it.
+
+## Default skills (auto-load)
+
+A "default" is a skill your agent loads automatically on every session start.
+It's a flag **independent** of enable/disable (a skill can be a default without
+being active). Mark one with `skill default <name>` (or `-g` for every project),
+list them with `skill defaults`. The AGENTS.md bootstrap block tells your agent to
+run `skill defaults` then `skill cat <name>` for each.
+
+Defaults live in `skill.config` (`defaults:`) and `config.yaml` (`defaults_global:`).
+
 ## Bootstrap
 
 `skill init -g` injects a short, idempotent block into each detected agent's global
 instruction file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`):
 
+> On session start, run `skill defaults` and load each with `skill cat <name>`.
 > When the user types `/X`, run `skill trigger X`. Single match → apply the output;
 > multiple → show candidates; load each skill only once per session.
 
@@ -166,7 +211,7 @@ git clone https://github.com/victortomaili/skill-cli
 cd skill-cli
 npm install
 npm link            # makes `skill` point at your checkout
-npm test            # 157 tests, network-free (~3s)
+npm test            # 225 tests, network-free (~3s)
 npm run test:e2e    # opt-in: real npx fetch over the network
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@victortomaili/skill-cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Cross-agent skill manager — one global store, clean agent folders, activation via skill.config",
   "license": "MIT",
   "author": "Victor Tomaili <victor@tomaili.com>",
@@ -30,6 +30,8 @@
     "test:e2e": "node scripts/e2e.mjs"
   },
   "dependencies": {
+    "@inquirer/core": "^11.2.1",
+    "@inquirer/prompts": "^8.5.2",
     "picocolors": "^1.1.1",
     "yaml": "^2.6.0"
   },

package/src/cli.js

@@ -9,23 +9,36 @@ import { cmdEnable } from './commands/enable.js'
 import { cmdDisable } from './commands/disable.js'
 import { cmdInstall } from './commands/install.js'
 import { cmdUpdate } from './commands/update.js'
+import { cmdRemove } from './commands/remove.js'
+import { cmdSearch } from './commands/search.js'
+import { cmdManager } from './commands/manager.js'
+import { cmdDefaults, cmdDefault, cmdUndefault } from './commands/defaults.js'
+import { isInteractive } from './lib/interactive.js'
 import { VERSION } from './lib/version.js'
 
 const HELP = `${c.bold('skill')} ${c.gray('v' + VERSION)} — cross-agent skill manager
 ${c.gray('Single global store + activation (skill.config) + bootstrap (AGENTS.md).')}
 
+${c.bold('skill')}                  ${c.gray('interactive manager (↑↓ space d enter — TTY only)')}
+
 ${c.bold('Setup')}
   ${c.cyan('skill init -g')}              global setup (store + AGENTS.md injection)
   ${c.cyan('skill init')}                 create skill.config for this project
 
 ${c.bold('Acquire skills')}
   ${c.cyan('skill install')} ${c.gray('<source>')}    fetch to store via npx skills (agent dirs untouched)
+  ${c.cyan('skill search')}                  interactive search & multi-install (TTY only)
 
 ${c.bold('Activation')}
   ${c.cyan('skill enable')} ${c.gray('<name> [-g]')}  enable in project, or globally (-g)
   ${c.cyan('skill disable')} ${c.gray('<name> [-g]')} disable
   ${c.cyan('skill list')}                  installed + active skills (cwd-aware)
 
+${c.bold('Defaults (auto-load)')}
+  ${c.cyan('skill default')} ${c.gray('<name> [-g]')} mark a skill for auto-load on session start
+  ${c.cyan('skill undefault')} ${c.gray('<name> [-g]')} remove the default flag
+  ${c.cyan('skill defaults')}                 list default skills (agent runs this on start)
+
 ${c.bold('Usage (agent)')}
   ${c.cyan('skill show')} ${c.gray('<name>')}         metadata + path + triggers
   ${c.cyan('skill cat')} ${c.gray('<name>')}          dump content to context
@@ -33,6 +46,7 @@ ${c.bold('Usage (agent)')}
 
 ${c.bold('Maintenance')}
   ${c.cyan('skill update')} ${c.gray('[name|--all]')} refresh store from source
+  ${c.cyan('skill remove')} ${c.gray('<name> [-y]')}  remove from store (prompt unless -y / non-TTY)
 
 ${c.gray('Source formats (install): owner/repo | github/gitlab URL | git URL | local path | npm package')}
 ${c.gray('Test (no real ~ touched): SKILL_CLI_HOME=/tmp/sktest skill init -g')}
@@ -44,20 +58,46 @@ ${c.bold('★ Enjoying skill-cli?')} ${c.gray('Star the repo — it helps others
 
 const [, , cmd, ...rest] = process.argv
 
-try {
+async function main() {
   switch (cmd) {
+    case 'manager': case 'ui':
+      if (!isInteractive()) {
+        console.error(c.red("'skill manager' is interactive — run it in a terminal, or use 'skill list'."))
+        process.exit(1)
+      }
+      await cmdManager()
+      break
     case undefined:
+      if (isInteractive()) { await cmdManager() }
+      else { console.log(HELP) }
+      break
     case '-h': case '--help': case 'help':
       console.log(HELP); break
     case 'init': cmdInit(rest); break
-    case 'install': case 'add': cmdInstall(rest); break
+    case 'install': case 'add':
+      // No source + a real terminal → interactive search TUI. Agents/CI (non-TTY)
+      // and explicit sources stay non-interactive.
+      if (rest.length === 0 && isInteractive()) { await cmdSearch(rest) }
+      else { cmdInstall(rest) }
+      break
+    case 'search': case 'browse':
+      if (!isInteractive()) {
+        console.error(c.red("'skill search' is interactive — run it in a terminal, or use 'skill install <source>'."))
+        process.exit(1)
+      }
+      await cmdSearch(rest)
+      break
     case 'enable': cmdEnable(rest); break
     case 'disable': cmdDisable(rest); break
     case 'list': case 'ls': cmdList(rest); break
+    case 'defaults': cmdDefaults(rest); break
+    case 'default': case 'def': cmdDefault(rest); break
+    case 'undefault': case 'undef': cmdUndefault(rest); break
     case 'show': case 'info': cmdShow(rest); break
     case 'cat': cmdCat(rest); break
     case 'trigger': cmdTrigger(rest); break
     case 'update': cmdUpdate(rest); break
+    case 'remove': case 'rm': case 'uninstall': cmdRemove(rest); break
     case '-v': case '--version':
       console.log('skill-cli ' + VERSION); break
     default:
@@ -65,7 +105,9 @@ try {
       console.error(c.gray('  skill --help'))
       process.exit(1)
   }
-} catch (e) {
+}
+
+main().catch(e => {
   console.error(c.red('Error: ') + e.message)
   process.exit(1)
-}
+})

package/src/commands/defaults.js

@@ -0,0 +1,92 @@
+import c from 'picocolors'
+import { listStore } from '../lib/store.js'
+import { readGlobalConfig, writeGlobalConfig, readProjectConfig, writeProjectConfig, computeDefaults } from '../lib/config.js'
+import { trunc } from '../lib/format.js'
+
+// `skill defaults` — list the skills marked as defaults (auto-loaded on agent
+// session start). This is the agent-facing command the AGENTS.md block tells the
+// agent to run, then `skill cat <name>` for each. cwd-aware (global + project).
+export function cmdDefaults() {
+  const installed = listStore()
+  const globalCfg = readGlobalConfig()
+  const projCfg = readProjectConfig()
+  const eff = computeDefaults(installed, globalCfg, projCfg)
+
+  const scope = projCfg ? c.magenta(process.cwd()) : c.gray('(global)')
+  console.log(c.bold('skill defaults') + c.gray(' — auto-load on session start · project: ') + scope)
+  console.log()
+
+  if (eff.length === 0) {
+    console.log(c.gray('  No default skills yet. Mark with: ') + c.cyan('skill default <name>'))
+    return
+  }
+
+  for (const name of eff) {
+    const s = installed.find(x => x.name === name)
+    const trg = s && s.triggers.length ? '  ' + c.gray('/' + s.triggers.join(', /')) : ''
+    console.log(`  ${c.yellow('★')} ${c.bold(name.padEnd(22))}${trg}`)
+    if (s && s.description) console.log(c.gray('      ' + trunc(s.description, 66)))
+  }
+  console.log()
+  console.log(c.gray('Load each into context: ') + c.cyan('skill cat <name>'))
+}
+
+// `skill default <name> [-g]` — mark a skill as a default (auto-load). Requires
+// the skill to be installed (a typo would silently "succeed" but never resolve).
+export function cmdDefault(args) {
+  const global = args.includes('-g') || args.includes('--global')
+  const name = args.find(a => !a.startsWith('-'))
+  if (!name) {
+    console.error(c.red('Usage: skill default <name> [-g]'))
+    console.error(c.gray('  Marks a skill as a default (auto-loaded on agent session start).'))
+    process.exit(1)
+  }
+  if (!listStore().some(s => s.name.toLowerCase() === name.toLowerCase())) {
+    console.error(c.red('Not installed: ' + name))
+    console.error(c.gray('  Install first: skill install <source>'))
+    process.exit(1)
+  }
+  if (global) {
+    const cfg = readGlobalConfig()
+    if (!(cfg.defaults_global || []).some(d => d.toLowerCase() === name.toLowerCase())) {
+      cfg.defaults_global.push(name.toLowerCase())
+      cfg.defaults_global.sort()
+    }
+    writeGlobalConfig(cfg)
+    console.log(c.green('✓') + ' default globally: ' + c.bold(name) + c.gray('  (auto-load in every project)'))
+  } else {
+    const cwd = process.cwd()
+    const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [], defaults: [] }
+    if (!(cfg.defaults || []).some(d => d.toLowerCase() === name.toLowerCase())) cfg.defaults.push(name.toLowerCase())
+    writeProjectConfig(cwd, cfg)
+    console.log(c.green('✓') + ' default in project: ' + c.bold(name) + c.gray('  (' + cwd + ')'))
+  }
+}
+
+// `skill undefault <name> [-g]` — remove the default flag.
+export function cmdUndefault(args) {
+  const global = args.includes('-g') || args.includes('--global')
+  const name = args.find(a => !a.startsWith('-'))
+  if (!name) {
+    console.error(c.red('Usage: skill undefault <name> [-g]'))
+    process.exit(1)
+  }
+  if (global) {
+    const cfg = readGlobalConfig()
+    const had = (cfg.defaults_global || []).some(d => d.toLowerCase() === name.toLowerCase())
+    cfg.defaults_global = (cfg.defaults_global || []).filter(d => d.toLowerCase() !== name.toLowerCase())
+    writeGlobalConfig(cfg)
+    console.log(had
+      ? (c.green('✓') + ' removed global default: ' + c.bold(name))
+      : (c.gray('·') + ' not a global default: ' + c.bold(name) + c.gray(' (nothing to do)')))
+  } else {
+    const cwd = process.cwd()
+    const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [], defaults: [] }
+    const had = (cfg.defaults || []).some(d => d.toLowerCase() === name.toLowerCase())
+    cfg.defaults = (cfg.defaults || []).filter(d => d.toLowerCase() !== name.toLowerCase())
+    writeProjectConfig(cwd, cfg)
+    console.log(had
+      ? (c.green('✓') + ' removed project default: ' + c.bold(name))
+      : (c.gray('·') + ' not a project default: ' + c.bold(name) + c.gray(' (nothing to do)')))
+  }
+}

package/src/commands/install.js

@@ -14,17 +14,10 @@ function resolveSource(source) {
   return source
 }
 
-// Fetch skill(s) from ANY source `npx skills` understands — github owner/repo,
-// full GitHub/GitLab URL, git URL, local path, npm package — into a TEMP cwd,
-// then move the files into our store. Agent folders stay untouched.
-export function cmdInstall(args) {
-  const source = args[0]
-  if (!source) {
-    console.error(c.red('Usage: skill install <source>'))
-    console.error(c.gray('  source: owner/repo | github/gitlab URL | git URL | local path | npm package'))
-    process.exit(1)
-  }
-
+// Fetch skill(s) from `source` into the store. Throws on failure (does NOT
+// process.exit) so callers — the `install` command AND the `search` TUI loop —
+// can decide how to handle errors. Returns the list of moved skill names.
+export function installSource(source) {
   const resolved = resolveSource(source)
   console.log(c.cyan('Fetching: ') + resolved)
   console.log(c.gray('  via npx skills add (temp cwd; agent folders untouched)'))
@@ -33,9 +26,7 @@ export function cmdInstall(args) {
   try {
     ({ tmp, fetchedDir } = fetchSkillsToTemp(resolved))
   } catch (e) {
-    console.error(c.red(e.message))
-    console.error(c.gray('Check the source (owner/repo, URL, path, npm package).'))
-    process.exit(1)
+    throw new Error(e.message)
   }
 
   try {
@@ -84,7 +75,27 @@ export function cmdInstall(args) {
     }
     console.log()
     console.log(c.gray('Skills are passive until enabled. Activate with: ') + c.cyan('skill enable <name>') + c.gray(' or ') + c.cyan('-g'))
+    return moved
   } finally {
     if (tmp) fs.rmSync(tmp, { recursive: true, force: true })
   }
 }
+
+// `skill install <source>` — non-interactive. The TTY/no-args route to the search
+// TUI is handled in cli.js (avoids a circular import with search.js).
+export function cmdInstall(args) {
+  const source = args[0]
+  if (!source) {
+    console.error(c.red('Usage: skill install <source>'))
+    console.error(c.gray('  source: owner/repo | owner/repo@skill | github/gitlab URL | git URL | local path | npm package'))
+    console.error(c.gray('  (in a terminal with no source → interactive search: skill search)'))
+    process.exit(1)
+  }
+  try {
+    installSource(source)
+  } catch (e) {
+    console.error(c.red(e.message))
+    console.error(c.gray('Check the source (owner/repo, URL, path, npm package).'))
+    process.exit(1)
+  }
+}

package/src/commands/list.js

@@ -1,6 +1,6 @@
 import c from 'picocolors'
 import { listStore } from '../lib/store.js'
-import { readGlobalConfig, readProjectConfig, computeEffective } from '../lib/config.js'
+import { readGlobalConfig, readProjectConfig, computeEffective, computeDefaults } from '../lib/config.js'
 import { trunc } from '../lib/format.js'
 
 export function cmdList(_args = []) {
@@ -8,6 +8,7 @@ export function cmdList(_args = []) {
   const globalCfg = readGlobalConfig()
   const projCfg = readProjectConfig()
   const effective = computeEffective(installed, globalCfg, projCfg)
+  const defaults = computeDefaults(installed, globalCfg, projCfg)
 
   const scope = projCfg ? c.magenta(process.cwd()) : c.gray('(global)')
   console.log(c.bold('skill list') + c.gray(' — project: ') + scope)
@@ -21,13 +22,14 @@ export function cmdList(_args = []) {
   for (const s of installed) {
     const active = effective.includes(s.name)
     const mark = active ? c.green('●') : c.gray('○')
+    const star = defaults.includes(s.name) ? c.yellow('★') : c.gray('·')
     const sc = labelScope(s.name, globalCfg, projCfg)
     const trg = s.triggers.length ? '  ' + c.gray('/' + s.triggers.join(', /')) : ''
-    console.log(`  ${mark} ${c.bold(s.name.padEnd(22))} ${c.gray(String(s.version).padEnd(8))} ${sc}${trg}`)
+    console.log(`  ${mark} ${star} ${c.bold(s.name.padEnd(22))} ${c.gray(String(s.version).padEnd(8))} ${sc}${trg}`)
     if (s.description) console.log(c.gray('      ' + trunc(s.description, 68)))
   }
   console.log()
-  console.log(c.green('● active   ') + c.gray('○ passive (installed but not enabled in this project)'))
+  console.log(c.green('● active   ') + c.gray('○ passive   ') + c.yellow('★ default (auto-load on session start)'))
   console.log(c.cyan('Details: ') + 'skill show <name>   ' + c.cyan('Load: ') + 'skill cat <name>')
 }
 

package/src/commands/manager.js

@@ -0,0 +1,191 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createPrompt, useState, useKeypress, usePrefix, isEnterKey, isUpKey, isDownKey } from '@inquirer/core'
+import c from 'picocolors'
+import { STORE_DIR } from '../lib/paths.js'
+import { listStore } from '../lib/store.js'
+import { readGlobalConfig, readProjectConfig, writeProjectConfig, computeEffective, computeDefaults } from '../lib/config.js'
+import { cleanConfig } from './remove.js'
+import { trunc } from '../lib/format.js'
+
+const KEYS = c.gray('↑↓ move · space toggle · a default · d delete · enter view · q/esc quit')
+
+// where a skill's activation currently comes from (mirrors `skill list`)
+function labelScope(name, g, p) {
+  if (p && (p.allow || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.magenta('project')
+  if ((g.enabled_global || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.blue('global ')
+  return c.gray('-      ')
+}
+
+// Pure decision: given the current configs, compute the new {allow, deny} arrays
+// that flip `name`'s active state in THIS project. No I/O → unit-testable without
+// SKILL_CLI_HOME. enabled_global is untouched (the manager toggle is project-scoped).
+//   passive → add to project allow (active here)
+//   active via project allow → remove from allow
+//   active via global only → add a local deny so it goes passive HERE
+export function computeToggle(installed, globalCfg, projCfg, name) {
+  const lc = String(name).toLowerCase()
+  const p = {
+    inherit: projCfg?.inherit !== false,
+    deny: [...(projCfg?.deny || [])],
+    allow: [...(projCfg?.allow || [])],
+  }
+  const active = computeEffective(installed, globalCfg, p).includes(name)
+  const isGlobal = (globalCfg.enabled_global || []).some(a => String(a).toLowerCase() === lc)
+  const isProjectAllow = p.allow.some(a => String(a).toLowerCase() === lc)
+  if (active) {
+    p.allow = p.allow.filter(a => String(a).toLowerCase() !== lc)
+    if (isGlobal && !isProjectAllow) {
+      if (!p.deny.some(d => String(d).toLowerCase() === lc)) p.deny.push(lc)
+    }
+  } else {
+    p.deny = p.deny.filter(d => String(d).toLowerCase() !== lc)
+    if (!p.allow.some(a => String(a).toLowerCase() === lc)) p.allow.push(lc)
+  }
+  return { allow: p.allow, deny: p.deny }
+}
+
+// Apply computeToggle's decision to disk and return a status line for the UI.
+export function toggleActive(name, cwd = process.cwd()) {
+  const installed = listStore()
+  const g = readGlobalConfig()
+  const p = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [] }
+  const wasActive = computeEffective(installed, g, p).includes(name)
+  const next = computeToggle(installed, g, p, name)
+  writeProjectConfig(cwd, { ...p, ...next })
+  return wasActive ? (c.gray('· disabled in project: ') + name) : (c.green('✓ enabled in project: ') + name)
+}
+
+function removeOne(name) {
+  fs.rmSync(path.join(STORE_DIR, name), { recursive: true, force: true })
+  cleanConfig(name)
+}
+
+// Bounded view of SKILL.md — the full file can be large and inquirer does not scroll.
+function viewBody(s) {
+  const file = path.join(STORE_DIR, s.name, 'SKILL.md')
+  let content
+  try { content = fs.readFileSync(file, 'utf8') } catch { return c.gray('  (no SKILL.md)') }
+  const lines = content.split(/\r?\n/)
+  const max = 22
+  const shown = lines.slice(0, max).map(l => (l ? '  ' + l : ''))
+  if (lines.length > max) shown.push(c.gray('  … ' + (lines.length - max) + ' more lines — `skill cat ' + s.name + '`'))
+  return shown.join('\n')
+}
+
+// Pure decision: the new project `defaults` array after toggling `name`'s default
+// flag. (The manager `a` key is project-scoped; global defaults use the CLI.)
+export function computeToggleDefault(projCfg, name) {
+  const lc = String(name).toLowerCase()
+  const defs = [...(projCfg?.defaults || [])]
+  return defs.some(d => String(d).toLowerCase() === lc)
+    ? defs.filter(d => String(d).toLowerCase() !== lc)
+    : [...defs, lc]
+}
+
+// Apply the default toggle to disk and return a status line for the UI.
+function toggleDefault(name, cwd = process.cwd()) {
+  const installed = listStore()
+  const g = readGlobalConfig()
+  const p = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [], defaults: [] }
+  const wasDefault = computeDefaults(installed, g, p).includes(name)
+  const next = computeToggleDefault(p, name)
+  writeProjectConfig(cwd, { ...p, defaults: next })
+  return wasDefault ? (c.gray('· un-defaulted: ') + name) : (c.yellow('★ default: ') + name + c.gray(' (auto-load)'))
+}
+
+// Clamp a cursor move so it can't leave the list bounds (pure → unit-tested).
+export function moveCursor(cur, length, delta) {
+  if (length <= 0) return 0
+  return Math.max(0, Math.min(length - 1, cur + delta))
+}
+
+// One custom prompt owns the whole keyboard loop (select/checkbox can't do `d`/view).
+//   ↑↓ move · space toggle active in this project · d delete (confirm) ·
+//   enter view the SKILL.md · q quit. Re-reads the store/config every render so
+//   toggles & deletes are reflected immediately.
+const managerPrompt = createPrompt((_config, done) => {
+  const [cursor, setCursor] = useState(0)
+  const [mode, setMode] = useState('list')      // 'list' | 'confirm' | 'view'
+  const [tick, setTick] = useState(0)           // bump (a VALUE, not a fn) to force a re-render
+  const [status, setStatus] = useState('')
+  const prefix = usePrefix({ theme: { prefix: { idle: c.cyan('?'), done: c.cyan('✓') } } })
+
+  const installed = listStore()
+  const g = readGlobalConfig()
+  const p = readProjectConfig()
+  const eff = computeEffective(installed, g, p)
+  const defs = computeDefaults(installed, g, p)
+  const cur = installed.length ? Math.max(0, Math.min(cursor, installed.length - 1)) : 0
+  const s = installed[cur]
+
+  useKeypress((key) => {
+    if (mode === 'view') { setMode('list'); return }            // any key → back to list
+    if (mode === 'confirm') {
+      if (key.name === 'y') {
+        if (s) { removeOne(s.name); setStatus(c.red('✓ removed ') + s.name) }
+        setMode('list'); setTick(tick + 1)
+      } else if (key.name === 'escape' || key.name === 'n' || (key.ctrl && key.name === 'c')) {
+        setMode('list'); setStatus(c.gray('cancelled'))
+      }
+      return
+    }
+    // list mode
+    // NB: @inquirer/core's useState setter takes a VALUE (there is NO functional
+    // updater like React's). We read the clamped `cur` from THIS render's closure —
+    // useKeypress keeps the handler fresh on every render, so it's always current.
+    if (isUpKey(key)) { setCursor(moveCursor(cur, installed.length, -1)); setStatus('') }
+    else if (isDownKey(key)) { setCursor(moveCursor(cur, installed.length, 1)); setStatus('') }
+    else if (key.name === 'space') { if (s) { setStatus(toggleActive(s.name)); setTick(tick + 1) } }
+    else if (key.name === 'a') { if (s) { setStatus(toggleDefault(s.name)); setTick(tick + 1) } }
+    else if (key.name === 'd') { if (s) { setMode('confirm'); setStatus('') } }
+    else if (isEnterKey(key)) { if (s) { setMode('view'); setStatus('') } }
+    else if (key.name === 'q' || key.name === 'escape' || (key.ctrl && key.name === 'c')) done()
+  })
+
+  // ── render ──
+  if (mode === 'view' && s) {
+    return prefix + ' ' + c.bold(s.name) + c.gray('  (any key to go back)') + '\n' + viewBody(s)
+  }
+  const lines = [prefix + ' ' + c.bold('skill manager') + c.gray(' — ' + installed.length + ' installed · ' + eff.length + ' active')]
+  for (let i = 0; i < installed.length; i++) {
+    const sk = installed[i]
+    const active = eff.includes(sk.name)
+    const arrow = i === cur ? c.cyan('❯') : ' '
+    const mark = active ? c.green('●') : c.gray('○')
+    const star = defs.includes(sk.name) ? c.yellow('★') : c.gray('·')
+    const sc = labelScope(sk.name, g, p)
+    const trg = sk.triggers.length ? '  ' + c.gray('/' + sk.triggers.join(', /')) : ''
+    const nameStr = sk.name.padEnd(24)
+    const nameCol = i === cur ? c.bold(nameStr) : nameStr
+    lines.push(`${arrow} ${mark} ${star} ${nameCol} ${c.gray(String(sk.version || '').padEnd(8))} ${sc}${trg}`)
+    if (i === cur && sk.description) lines.push(c.gray('      ' + trunc(sk.description, 62)))
+  }
+  lines.push(c.gray('  ' + '─'.repeat(58)))
+  lines.push('  ' + KEYS)
+  if (mode === 'confirm') {
+    lines.push('')
+    lines.push('  ' + c.yellow('Delete ' + c.bold(s ? s.name : '') + '? [y/N] ') + c.gray('(N keeps it)'))
+  } else if (status) {
+    lines.push('  ' + status)
+  }
+  return lines.join('\n')
+})
+
+// `skill` (no args) / `skill manager` / `skill ui` on a terminal. Agents/CI never
+// reach here (cli.js gates on isInteractive).
+export async function cmdManager() {
+  const installed = listStore()
+  if (installed.length === 0) {
+    console.log(c.yellow('Store empty.') + c.gray('  Install a skill first: ') + c.cyan('skill install <source>'))
+    return
+  }
+  try {
+    await managerPrompt({})
+  } catch { /* Ctrl-C / abort — fall through to the footer */ }
+  const g = readGlobalConfig()
+  const p = readProjectConfig()
+  const eff = computeEffective(listStore(), g, p)
+  console.log()
+  console.log(c.gray('Closed. ' + listStore().length + ' installed · ' + eff.length + ' active in ' + process.cwd()))
+}

package/src/commands/remove.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import c from 'picocolors'
+import { STORE_DIR } from '../lib/paths.js'
+import { listStore } from '../lib/store.js'
+import { readGlobalConfig, writeGlobalConfig, readProjectConfig, writeProjectConfig } from '../lib/config.js'
+import { pad } from '../lib/format.js'
+import { isInteractive } from '../lib/interactive.js'
+
+// Read one line from stdin (fd 0) synchronously. Only ever called when stdin is
+// a TTY (or SKILL_CLI_FORCE_TTY is set), so it blocks for the user's keystrokes.
+function readLine() {
+  let line = ''
+  const buf = Buffer.alloc(1)
+  while (true) {
+    let n
+    try { n = fs.readSync(0, buf, 0, 1, null) } catch { return line }
+    if (n === 0) break                       // EOF
+    const ch = buf[0]
+    if (ch === 0x0A || ch === 0x0D) break    // \n or \r — end of line
+    if (ch === 0x03) process.exit(130)       // Ctrl-C
+    line += String.fromCharCode(ch)
+  }
+  return line.trim()
+}
+
+function confirm(question) {
+  process.stdout.write(question)
+  const a = readLine().toLowerCase()
+  return a === 'y' || a === 'yes'
+}
+
+// `skill remove <name>... [-y|--yes|-f|--force]`
+//
+//   TTY + no --yes  → y/N confirmation prompt (default keeps the skill)
+//   non-TTY (agent/CI/pipe) OR --yes → remove without prompting
+//
+// The destination name is canonicalized via listStore (case-insensitive, and an
+// unknown/`../x` name can never reach path.join(STORE_DIR, name)). Also drops the
+// skill from the global enabled list and the current project's allow-list; other
+// projects may keep a now-dangling allow entry, but computeEffective filters
+// those out (harmless).
+export function cmdRemove(args) {
+  const assumeYes = args.some(a => ['-y', '--yes', '-f', '--force'].includes(a))
+  const requested = args.filter(a => !a.startsWith('-'))
+
+  if (requested.length === 0) {
+    console.error(c.red('Usage: skill remove <name>... [-y]'))
+    console.error(c.gray('  Removes skill(s) from the store. Agents/CI auto-skip the prompt, or pass -y.'))
+    process.exit(1)
+  }
+
+  const installed = listStore()
+  const byLower = new Map(installed.map(s => [s.name.toLowerCase(), s.name]))
+  const targets = []
+  const seen = new Set()
+  for (const a of requested) {
+    const canon = byLower.get(a.toLowerCase())
+    if (!canon) { console.log(c.yellow('  · ' + pad(a)) + c.yellow('not installed — skipping')); continue }
+    // dedupe exact + case-variant duplicates (foo, FOO, foo → a single removal,
+    // not three, so the count and prompt list stay accurate)
+    const key = canon.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    targets.push(canon)
+  }
+
+  if (targets.length === 0) {
+    console.log(c.gray('Nothing to remove.'))
+    return
+  }
+
+  if (isInteractive() && !assumeYes) {
+    const what = targets.length === 1 ? `skill ${c.bold(targets[0])}` : `${targets.length} skills`
+    const list = targets.map(t => '  • ' + t).join('\n')
+    if (!confirm(c.yellow(`About to remove ${what}:\n${list}\n`) + c.bold('Remove? [y/N] '))) {
+      console.log(c.gray('Aborted. Nothing removed.'))
+      return
+    }
+  }
+
+  let removed = 0
+  for (const name of targets) {
+    fs.rmSync(path.join(STORE_DIR, name), { recursive: true, force: true })
+    cleanConfig(name)
+    console.log(c.green('  ✓ ') + c.bold(pad(name)) + c.gray('removed'))
+    removed++
+  }
+  console.log()
+  console.log(c.green(`✓ ${removed} skill(s) removed`))
+}
+
+// Drop the skill from the global enabled list and the current project allow-list.
+// Exported so the interactive manager can reuse it on its `d` (delete) action.
+export function cleanConfig(name) {
+  const g = readGlobalConfig()
+  if ((g.enabled_global || []).some(a => a.toLowerCase() === name.toLowerCase())) {
+    g.enabled_global = (g.enabled_global || []).filter(a => a.toLowerCase() !== name.toLowerCase())
+    writeGlobalConfig(g)
+  }
+  const cwd = process.cwd()
+  const p = readProjectConfig(cwd)
+  if (p && (p.allow || []).some(a => a.toLowerCase() === name.toLowerCase())) {
+    p.allow = (p.allow || []).filter(a => a.toLowerCase() !== name.toLowerCase())
+    writeProjectConfig(cwd, p)
+  }
+}

package/src/commands/search.js

@@ -0,0 +1,92 @@
+import { input, checkbox } from '@inquirer/prompts'
+import c from 'picocolors'
+import { searchSkills } from '../lib/skills-find.js'
+import { installSource } from './install.js'
+
+// Run an @inquirer prompt that ALSO exits on ESC. The prebuilt input/checkbox
+// prompts only respond to Enter / Ctrl-C; we wire ESC to abort via the `signal`
+// (passed as the prompt's 2nd context arg → createPrompt's abort path, which
+// rejects with AbortPromptError). Ctrl-C still works (ExitPromptError). Tested
+// without a TTY by pre-aborting the signal (see test/cli/search.test.mjs).
+//
+// During a prompt createPrompt's readline (terminal:true) emits `keypress` on
+// process.stdin, so our listener receives the ESC and aborts. Exported so the
+// error-handling path is unit-testable.
+export async function withEscExit(run) {
+  const controller = new AbortController()
+  const onKey = (_ch, key) => { if (key && key.name === 'escape') controller.abort() }
+  process.stdin.on('keypress', onKey)
+  try {
+    return { aborted: false, value: await run(controller.signal) }
+  } catch (e) {
+    if (e && /^(Abort|Exit|Cancel)PromptError$/.test(e.name)) return { aborted: true }
+    throw e
+  } finally {
+    process.stdin.removeListener('keypress', onKey)
+  }
+}
+
+// Interactive search & multi-install (TTY only — cli.js gates on isInteractive).
+//
+//   type a query → `npx skills find <query>` → multi-select (space to mark,
+//   enter to install all marked) → loops back so you can search again.
+//   ESC (or an empty query) at any prompt quits.
+//
+// Non-interactive (agents/CI) never reaches here; they use `skill install <source>`.
+export async function cmdSearch() {
+  console.log(c.bold('skill search') + c.gray(' — discover & install from the skills ecosystem (skills.sh)'))
+  console.log(c.gray('  type a query · space to mark · enter to install marked · esc or empty query to quit'))
+  console.log()
+
+  let totalInstalled = 0
+  while (true) {
+    const q = await withEscExit(signal => input({ message: 'Search skills:', default: '' }, { signal }))
+    if (q.aborted) break                       // ESC / Ctrl-C → exit
+    const query = (q.value || '').trim()
+    if (!query) break                          // empty Enter → exit
+
+    let results
+    try {
+      results = searchSkills(query)
+    } catch (e) {
+      console.error(c.red('  ' + e.message))
+      continue
+    }
+    if (results.length === 0) {
+      console.log(c.gray('  no skills matched "' + query + '".'))
+      continue
+    }
+
+    const choices = results.map(r => ({
+      name: `${r.skill}  ${c.gray(r.owner + '/' + r.repo)}  ${c.gray('(' + (r.installs || '?') + ' installs)')}`,
+      value: r.source,
+      short: r.skill,
+    }))
+
+    const sel = await withEscExit(signal => checkbox({
+      message: `Results for "${query}" — space to mark, enter to install (esc to quit):`,
+      choices,
+      pageSize: 12,
+    }, { signal }))
+    if (sel.aborted) break                     // ESC / Ctrl-C → exit
+    const selected = sel.value || []
+    if (selected.length === 0) {
+      console.log(c.gray('  nothing marked — search again, or esc / empty query to quit.'))
+      continue
+    }
+
+    for (const src of selected) {
+      console.log()
+      try {
+        installSource(src)
+        totalInstalled++
+      } catch (e) {
+        console.error(c.red('  install failed for ' + src + ': ' + (e.message || e)))
+      }
+    }
+    console.log()
+    console.log(c.green(`✓ ${selected.length} selected this round.`) + c.gray('  Search again, or esc / empty query to finish.'))
+    console.log()
+  }
+  console.log(c.gray(`\nDone. ${totalInstalled} skill(s) installed this session.`))
+}

package/src/lib/agents-md.js

@@ -19,6 +19,10 @@ Usage:
 - \`skill show <name>\` — skill summary (path, triggers, version)
 - \`skill cat <name>\` — load skill content into context
 
+Defaults: on session start, run \`skill defaults\` to list skills marked for
+auto-load, then \`skill cat <name>\` for each. Mark your own with
+\`skill default <name>\` (or \`-g\` for every project).
+
 Triggers: when the user types \`/X\`, run \`skill trigger X\`.
 - Single match → apply the output directly.
 - Multiple matches → show the candidate list; load the right one with \`skill cat <name>\`.

package/src/lib/config.js

@@ -7,6 +7,7 @@ const DEFAULT_GLOBAL = {
   version: 1,
   store: STORE_DIR,
   enabled_global: [],
+  defaults_global: [],
 }
 
 export function readGlobalConfig() {
@@ -29,6 +30,7 @@ export function writeGlobalConfig(cfg) {
     version: cfg.version ?? 1,
     store: cfg.store ?? STORE_DIR,
     enabled_global: cfg.enabled_global || [],
+    defaults_global: cfg.defaults_global || [],
   }
   fs.writeFileSync(GLOBAL_CONFIG, yaml.stringify(out), 'utf8')
 }
@@ -47,7 +49,7 @@ export function readProjectConfig(cwd = process.cwd()) {
     process.stderr.write('skill.config: parse error (' + (e.message || e) + ') — using global behavior\n')
     return null
   }
-  return { inherit: true, deny: [], allow: [], ...(parsed || {}) }
+  return { inherit: true, deny: [], allow: [], defaults: [], ...(parsed || {}) }
 }
 
 export function writeProjectConfig(cwd, cfg) {
@@ -56,6 +58,7 @@ export function writeProjectConfig(cwd, cfg) {
     inherit: cfg.inherit !== false,
     deny: cfg.deny || [],
     allow: cfg.allow || [],
+    defaults: cfg.defaults || [],
   }
   fs.writeFileSync(projectConfigPath(cwd), yaml.stringify(out), 'utf8')
 }
@@ -98,3 +101,17 @@ export function computeEffective(installed, globalCfg, projCfg) {
     .map(n => canonByLower.get(n))
     .sort()
 }
+
+// Effective DEFAULT skills (auto-loaded on agent session start), as CANONICAL
+// names. Independent of enable/disable: a skill may be active-but-not-default or
+// default-but-not-active. Inherits global defaults unless the project sets
+// inherit:false. Case-insensitive throughout.
+export function computeDefaults(installed, globalCfg, projCfg) {
+  const canonByLower = new Map(installed.map(s => [String(s.name).toLowerCase(), s.name]))
+  const set = new Set()
+  if (!projCfg || projCfg.inherit !== false) {
+    for (const d of (globalCfg.defaults_global || [])) set.add(String(d).toLowerCase())
+  }
+  if (projCfg) for (const d of (projCfg.defaults || [])) set.add(String(d).toLowerCase())
+  return [...set].filter(n => canonByLower.has(n)).map(n => canonByLower.get(n)).sort()
+}

package/src/lib/interactive.js

@@ -0,0 +1,8 @@
+// Are we talking to a human at a terminal? Agents, CI, and pipes have a non-TTY
+// stdin and must NOT be shown an interactive prompt (they would hang waiting for
+// input that never arrives). Shared by `remove` (y/N confirm) and the TUI commands
+// (`search`, and the forthcoming manager). SKILL_CLI_FORCE_TTY lets tests exercise
+// the prompt branch on a piped stdin.
+export function isInteractive() {
+  return process.stdin.isTTY === true || process.env.SKILL_CLI_FORCE_TTY === '1'
+}

package/src/lib/npx.js

@@ -22,8 +22,26 @@ import os from 'node:os'
 // as a single argv element — no shell injection — and `--skill *` stays literal
 // (cmd.exe does no globbing and no POSIX shell is ever involved). npx must be on
 // PATH; it ships with node/npm on every platform.
+// Detect a `@skill` pin on the source (skills ecosystem: owner/repo@skill or a
+// URL@skill). SSH git URLs (`git@host:owner/repo`) start with git@ and are NOT a
+// pin. When the source is pinned we must NOT pass `--skill '*'` — that flag
+// overrides the pin and fetches every skill in the repo (verified), so a search
+// result like owner/repo@research would otherwise dump the whole repo.
+export function skillPin(source) {
+  if (typeof source !== 'string') return null
+  if (source.startsWith('git@')) return null
+  const at = source.lastIndexOf('@')
+  if (at <= 0) return null
+  const skill = source.slice(at + 1)
+  if (!skill || skill.includes('/') || skill.includes(':')) return null
+  return skill
+}
+
 export function buildNpxSpawn(source, platform = process.platform) {
-  const base = ['-y', 'skills', 'add', source, '--copy', '--agent', 'claude-code', '--skill', '*', '-y']
+  // pinned source (owner/repo@skill) → let the @pin select the skill (passing
+  // --skill '*' here would override it and grab the whole repo). Otherwise fetch all.
+  const skillArgs = skillPin(source) ? [] : ['--skill', '*']
+  const base = ['-y', 'skills', 'add', source, '--copy', '--agent', 'claude-code', ...skillArgs, '-y']
   return platform === 'win32'
     ? { cmd: 'cmd.exe', args: ['/c', 'npx', ...base] }
     : { cmd: 'npx', args: base }

package/src/lib/skills-find.js

@@ -0,0 +1,58 @@
+import { execFileSync } from 'node:child_process'
+
+// Parse the output of `npx skills find <query>` into structured results.
+// Output shape (after ANSI strip):
+//     owner/repo@skill   25.7K installs
+//     └ https://skills.sh/owner/repo/skill
+// Pure + exported so it is unit-testable without spawning npx.
+export function parseFind(raw) {
+  const clean = String(raw == null ? '' : raw).replace(/\x1b\[[0-9;]*m/g, '')
+  const lines = clean.split(/\r?\n/)
+  const out = []
+  const srcRe = /^([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)@([A-Za-z0-9._-]+)\s+([0-9.]+[KM]?)?\s*installs\b/
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(srcRe)
+    if (!m) continue
+    const [, owner, repo, skill, installs] = m
+    const urlM = (lines[i + 1] || '').match(/https:\/\/\S+/)
+    out.push({
+      source: `${owner}/${repo}@${skill}`,
+      owner, repo, skill,
+      installs: installs || '',
+      url: urlM ? urlM[0] : '',
+    })
+  }
+  return out
+}
+
+// Run `npx skills find <query>` non-interactively (empty stdin, CI=1) and parse.
+// Cross-platform: Windows spawns via cmd.exe (Node CVE-2024-27980 refuses npx.cmd
+// with shell:false). The query is validated to a safe charset so it never reaches
+// cmd.exe's metachar surface (& | < > etc.).
+export function searchSkills(query) {
+  const q = String(query || '').trim()
+  if (!q) return []
+  if (/[^A-Za-z0-9 .\/_-]/.test(q)) {
+    throw new Error('search query may only contain letters, numbers, spaces, and . / _ -')
+  }
+  const isWin = process.platform === 'win32'
+  const cmd = isWin ? 'cmd.exe' : 'npx'
+  const args = isWin ? ['/c', 'npx', '-y', 'skills', 'find', q] : ['-y', 'skills', 'find', q]
+  let raw
+  try {
+    raw = execFileSync(cmd, args, {
+      input: '',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      shell: false,
+      timeout: 60000,
+      env: { ...process.env, CI: '1' },
+    })
+  } catch (e) {
+    if (e.code === 'ENOENT') throw new Error('npx not found on PATH — is Node.js installed?')
+    const timedOut = e.signal === 'SIGTERM' || e.code === 'ETIMEDOUT'
+    if (timedOut) throw new Error('search timed out after 60s (network too slow?)')
+    throw new Error('skills find failed: ' + (((e.stderr || e.stdout || '').toString().trim().split('\n').pop()) || e.message))
+  }
+  return parseFind(raw)
+}