@victortomaili/skill-cli 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -11,6 +11,30 @@ 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.4.0] - 2026-07-07
+
+### Changed (breaking — config format)
+- **Unified the "default" and "enabled" concepts into ONE global list.** Previously there were two independent global lists — `enabled_global` (skills active by default in every project) and `defaults_global` (skills auto-loaded on session start, independent of active state). Now there is a single `defaults` list in `config.yaml`: a default skill is BOTH active by default in every project AND auto-loaded on session start. This dissolves the confusion where the manager used a hidden `deny` to turn off a global skill — a default is simply the active-by-default set, and a project refines it with `allow` / `deny`.
+  - `skill default <name>` is now always GLOBAL (the `-g` flag is accepted but a no-op). `skill enable -g <name>` and `skill default <name>` now do the same thing; `skill disable -g` / `skill undefault` remove it.
+  - The per-project `defaults:` key in `skill.config` is removed — defaults are a global concept only. A project refines the active set with `allow` / `deny` / `inherit` (see Activation).
+  - **Automatic migration:** a legacy `config.yaml` with `enabled_global:` and/or `defaults_global:` is folded into `defaults:` (the union of both, deduped) on the next write. No manual steps.
+- AGENTS.md bootstrap block: the "Defaults" line now describes the unified model (active by default + auto-load, global).
+
+### Added
+- `skill init -g` now bootstraps **pi** too — the AGENTS.md block is injected into `~/.pi/agent/AGENTS.md` (pi's global context file). Claude Code, Codex, Gemini, and pi are now all bootstrapped on a single re-run.
+
+## [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

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** — one global list: active by default in every project AND auto-loaded on 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,12 +58,13 @@ 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 defaults (active by default + auto-load)
 
-<project>/skill.config       ← per-project activation (inherit / deny / allow)
+<project>/skill.config       ← per-project overrides (inherit / deny / allow)
 ~/.claude/CLAUDE.md          ← bootstrap block injected by `skill init -g`
 ~/.codex/AGENTS.md             (idempotent — preserves your existing content)
 ~/.gemini/GEMINI.md
+~/.pi/agent/AGENTS.md
 ```
 
 Agents don't read `skill.config` directly — the CLI does. The agent only needs the
@@ -73,16 +77,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 enable <name> [-g]` | Enable in project, or globally with `-g` |
-| `skill disable <name> [-g]` | Disable |
-| `skill list` | Show installed + active skills (cwd-aware) |
+| `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]` | Allow in project, or global default with `-g` |
+| `skill disable <name> [-g]` | Deny in project, or remove global default with `-g` |
+| `skill default <name>` | Mark a default skill (global: active + auto-load) |
+| `skill undefault <name>` | Remove the default 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\|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), `rm`/`uninstall` (remove).
+Aliases: `ls` (list), `add` (install), `info` (show), `rm`/`uninstall` (remove), `browse` (search), `ui` (manager), `def` (default), `undef` (undefault).
 
 ## Install sources
 
@@ -121,29 +130,73 @@ for a minimal, copy-paste template.
 
 ## Activation
 
-Three layers, most-specific wins:
+One global concept, refined per project:
 
 1. **installed** — present in the store (passive)
-2. **enabled globally** — listed in `config.yaml`; active by default in every project
-3. **enabled per project** — in the project's `skill.config` `allow` list
+2. **default (global)** — listed in `config.yaml` `defaults:`; **active by default in every project** and **auto-loaded on agent session start**. Mark one with `skill default <name>` (or `skill enable -g`).
+3. **per-project override** — a project's `skill.config` refines the set:
+   - `allow` — activate an otherwise-passive skill **in this project only**
+   - `deny` — turn off a default skill **in this project only**
+   - `inherit: false` — ignore global defaults entirely (only `allow` applies)
 
-A project `skill.config` overrides the global set. Pure allowlist mode:
+A project with **no `skill.config`** inherits the global defaults (all active). Pure
+allowlist mode in a single project:
 
 ```yaml
 # <project>/skill.config
-inherit: true
-deny: ["*"]                    # block every globally-enabled skill in this project
-allow: [react-best-practices]  # then open them one by one
+inherit: false                 # ignore global defaults in this project
+allow: [react-best-practices]  # only this skill is active here
 ```
 
-> `allow` always wins over `deny`, so `deny: ["*"]` + `allow: [X]` = "only X".
-> Matching is case-insensitive throughout.
+> `allow` always wins over `deny`, so with `inherit: true` you can also write
+> `deny: ["*"]` + `allow: [X]` = "only X here". 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 global default (active + auto-load) |
+| `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
+
+A **default** is a skill that is **active by default in every project** AND
+**auto-loaded on agent session start** — one unified global list in `config.yaml`
+(`defaults:`). Mark one with `skill default <name>`, remove with
+`skill undefault <name>`, list them with `skill defaults`. The AGENTS.md bootstrap
+block tells your agent to run `skill defaults` on start, then `skill cat <name>`
+for each.
+
+Defaults are a **global** concept (never per-project). A project can still turn a
+default off locally with `skill disable <name>` (a project `deny`), or activate a
+non-default locally with `skill enable <name>` (a project `allow`) — see
+[Activation](#activation). In the interactive manager, `a` toggles the global
+default; `space` toggles the per-project override.
 
 ## 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.
 
@@ -151,7 +204,7 @@ It's wrapped in `<!-- BEGIN skill-cli --> … <!-- END skill-cli -->` markers, n
 duplicates, and preserves your existing file content. Re-run `init -g` any time —
 it reports `already set up` and rewrites nothing.
 
-**Supported agents:** Claude Code, Codex, Gemini. (Cursor uses `.cursor/rules` with
+**Supported agents:** Claude Code, Codex, Gemini, and pi. (Cursor uses `.cursor/rules` with
 a different format — adapter planned. See [issue tracker](https://github.com/victortomaili/skill-cli/issues).)
 
 ## Cross-platform
@@ -167,7 +220,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.2.0",
+  "version": "0.4.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

@@ -10,23 +10,35 @@ 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 enable')} ${c.gray('<name> [-g]')}  allow in project, or global default (-g)
+  ${c.cyan('skill disable')} ${c.gray('<name> [-g]')} deny in project, or remove global default (-g)
   ${c.cyan('skill list')}                  installed + active skills (cwd-aware)
 
+${c.bold('Defaults (active + auto-load)')}
+  ${c.cyan('skill default')} ${c.gray('<name>')}    mark a default skill (global: active in every project)
+  ${c.cyan('skill undefault')} ${c.gray('<name>')}  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
@@ -46,16 +58,41 @@ ${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
@@ -68,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,73 @@
+import c from 'picocolors'
+import { listStore } from '../lib/store.js'
+import { readGlobalConfig, writeGlobalConfig, computeDefaults } from '../lib/config.js'
+import { trunc } from '../lib/format.js'
+
+// `skill defaults` — list the skills marked as defaults. In the unified model a
+// default skill is BOTH active-by-default in every project AND auto-loaded on
+// agent session start (one global `defaults` list). This is the agent-facing
+// command the AGENTS.md block tells the agent to run, then `skill cat <name>`
+// for each. Defaults are a GLOBAL concept (never per-folder).
+export function cmdDefaults() {
+  const installed = listStore()
+  const globalCfg = readGlobalConfig()
+  const eff = computeDefaults(installed, globalCfg)
+
+  console.log(c.bold('skill defaults') + c.gray(' — active by default + auto-load on session start (global)'))
+  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>` — mark a skill as a default (active by default in every
+// project + auto-loaded on session start). Always GLOBAL. Requires the skill to
+// be installed (a typo would silently "succeed" but never resolve). `-g`/`--global`
+// is accepted for compatibility but is a no-op — defaults are inherently global.
+export function cmdDefault(args) {
+  const name = args.find(a => !a.startsWith('-'))
+  if (!name) {
+    console.error(c.red('Usage: skill default <name>'))
+    console.error(c.gray('  Marks a skill as a default: active by default in every project + auto-load on 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)
+  }
+  const cfg = readGlobalConfig()
+  if (!(cfg.defaults || []).some(d => d.toLowerCase() === name.toLowerCase())) {
+    cfg.defaults.push(name.toLowerCase())
+    cfg.defaults.sort()
+  }
+  writeGlobalConfig(cfg)
+  console.log(c.green('✓') + ' default (global): ' + c.bold(name) + c.gray('  (active + auto-load in every project)'))
+}
+
+// `skill undefault <name>` — remove the default flag (always global).
+export function cmdUndefault(args) {
+  const name = args.find(a => !a.startsWith('-'))
+  if (!name) {
+    console.error(c.red('Usage: skill undefault <name>'))
+    process.exit(1)
+  }
+  const cfg = readGlobalConfig()
+  const had = (cfg.defaults || []).some(d => d.toLowerCase() === name.toLowerCase())
+  cfg.defaults = (cfg.defaults || []).filter(d => d.toLowerCase() !== name.toLowerCase())
+  writeGlobalConfig(cfg)
+  console.log(had
+    ? (c.green('✓') + ' removed default: ' + c.bold(name))
+    : (c.gray('·') + ' not a default: ' + c.bold(name) + c.gray(' (nothing to do)')))
+}

package/src/commands/disable.js

@@ -8,12 +8,12 @@ export function cmdDisable(args) {
 
   if (global) {
     const cfg = readGlobalConfig()
-    const had = (cfg.enabled_global || []).some(a => a.toLowerCase() === name.toLowerCase())
-    cfg.enabled_global = (cfg.enabled_global || []).filter(a => a.toLowerCase() !== name.toLowerCase())
+    const had = (cfg.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())
+    cfg.defaults = (cfg.defaults || []).filter(a => a.toLowerCase() !== name.toLowerCase())
     writeGlobalConfig(cfg)
     console.log(had
-      ? (c.green('✓') + ' disabled globally: ' + c.bold(name))
-      : (c.gray('·') + ' not enabled globally: ' + c.bold(name) + c.gray(' (nothing to do)')))
+      ? (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: [] }

package/src/commands/enable.js

@@ -16,11 +16,11 @@ export function cmdEnable(args) {
 
   if (global) {
     const cfg = readGlobalConfig()
-    if (!cfg.enabled_global.some(a => a.toLowerCase() === name.toLowerCase())) {
-      cfg.enabled_global.push(name.toLowerCase()); cfg.enabled_global.sort()
+    if (!(cfg.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())) {
+      cfg.defaults.push(name.toLowerCase()); cfg.defaults.sort()
     }
     writeGlobalConfig(cfg)
-    console.log(c.green('✓') + ' enabled globally: ' + c.bold(name) + c.gray('  (active in all projects)'))
+    console.log(c.green('✓') + ' enabled globally (default): ' + c.bold(name) + c.gray('  (active + auto-load in all projects)'))
   } else {
     const cwd = process.cwd()
     const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [] }

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)
 
   const scope = projCfg ? c.magenta(process.cwd()) : c.gray('(global)')
   console.log(c.bold('skill list') + c.gray(' — project: ') + scope)
@@ -21,18 +22,19 @@ 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>')
 }
 
 function labelScope(name, globalCfg, projCfg) {
   if (projCfg && (projCfg.allow || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.magenta('project')
-  if ((globalCfg.enabled_global || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.blue('global ')
+  if ((globalCfg.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())) return c.blue('global ')
   return c.gray('-      ')
 }

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, writeGlobalConfig, 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.defaults || []).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. The global `defaults` list 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.defaults || []).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 global `defaults` array after toggling `name`'s default
+// flag. (Defaults are a GLOBAL concept — active by default + auto-load. The
+// manager `a` key edits this list; `space` does the per-folder allow/deny.)
+export function computeToggleDefault(list, name) {
+  const lc = String(name).toLowerCase()
+  const defs = [...(list || [])]
+  return defs.some(d => String(d).toLowerCase() === lc)
+    ? defs.filter(d => String(d).toLowerCase() !== lc)
+    : [...defs, lc]
+}
+
+// Apply the default toggle to the GLOBAL config and return a status line for the UI.
+function toggleDefault(name) {
+  const installed = listStore()
+  const g = readGlobalConfig()
+  const wasDefault = computeDefaults(installed, g).includes(name)
+  g.defaults = computeToggleDefault(g.defaults, name)
+  writeGlobalConfig(g)
+  return wasDefault ? (c.gray('· un-defaulted: ') + name) : (c.yellow('★ default: ') + name + c.gray(' (active + 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)
+  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

@@ -5,6 +5,7 @@ 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.
@@ -29,14 +30,6 @@ function confirm(question) {
   return a === 'y' || a === 'yes'
 }
 
-// Are we talking to a human at a terminal? Agents, CI, and pipes have a non-TTY
-// stdin and must NOT be prompted (they would hang waiting for input that never
-// arrives). SKILL_CLI_FORCE_TTY lets tests exercise the prompt branch by piping
-// an answer on a non-TTY stdin.
-function isInteractive() {
-  return process.stdin.isTTY === true || process.env.SKILL_CLI_FORCE_TTY === '1'
-}
-
 // `skill remove <name>... [-y|--yes|-f|--force]`
 //
 //   TTY + no --yes  → y/N confirmation prompt (default keeps the skill)
@@ -98,10 +91,11 @@ export function cmdRemove(args) {
 }
 
 // Drop the skill from the global enabled list and the current project allow-list.
-function cleanConfig(name) {
+// 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())
+  if ((g.defaults || []).some(a => a.toLowerCase() === name.toLowerCase())) {
+    g.defaults = (g.defaults || []).filter(a => a.toLowerCase() !== name.toLowerCase())
     writeGlobalConfig(g)
   }
   const cwd = process.cwd()

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 as
+defaults (active by default + auto-load), then \`skill cat <name>\` for each. Mark
+your own with \`skill default <name>\` (global — active in 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

@@ -6,7 +6,7 @@ import { CLI_ROOT, GLOBAL_CONFIG, PROJECT_CONFIG, STORE_DIR } from './paths.js'
 const DEFAULT_GLOBAL = {
   version: 1,
   store: STORE_DIR,
-  enabled_global: [],
+  defaults: [],
 }
 
 export function readGlobalConfig() {
@@ -17,7 +17,20 @@ export function readGlobalConfig() {
     process.stderr.write('skill-cli config: parse error (' + (e.message || e) + ') — using defaults\n')
     return { ...DEFAULT_GLOBAL }
   }
-  return { ...DEFAULT_GLOBAL, ...(parsed || {}) }
+  const merged = { ...DEFAULT_GLOBAL, ...(parsed || {}) }
+  // backward-compat: legacy configs split the active-by-default set
+  // (`enabled_global`) from the auto-load set (`defaults_global`). The unified
+  // model collapses them into one `defaults` list (a default skill is now BOTH
+  // active-by-default AND auto-loaded). On read, adopt the union of both legacy
+  // lists when no new-format `defaults` is present; `defaults` always wins.
+  if (!Array.isArray(merged.defaults) || merged.defaults.length === 0) {
+    const legacy = [
+      ...(Array.isArray(parsed?.enabled_global) ? parsed.enabled_global : []),
+      ...(Array.isArray(parsed?.defaults_global) ? parsed.defaults_global : []),
+    ]
+    if (legacy.length) merged.defaults = [...new Set(legacy.map(String))]
+  }
+  return merged
 }
 
 export function writeGlobalConfig(cfg) {
@@ -28,7 +41,7 @@ export function writeGlobalConfig(cfg) {
   const out = {
     version: cfg.version ?? 1,
     store: cfg.store ?? STORE_DIR,
-    enabled_global: cfg.enabled_global || [],
+    defaults: cfg.defaults || [],
   }
   fs.writeFileSync(GLOBAL_CONFIG, yaml.stringify(out), 'utf8')
 }
@@ -47,7 +60,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: [], ...(parsed || []) }
 }
 
 export function writeProjectConfig(cwd, cfg) {
@@ -78,7 +91,7 @@ function globMatch(pattern, name) {
 export function computeEffective(installed, globalCfg, projCfg) {
   const canonByLower = new Map(installed.map(s => [String(s.name).toLowerCase(), s.name]))
   const enabled = new Set(
-    (projCfg && projCfg.inherit === false ? [] : (globalCfg.enabled_global || []))
+    (projCfg && projCfg.inherit === false ? [] : (globalCfg.defaults || []))
       .map(s => String(s).toLowerCase())
   )
   if (projCfg) {
@@ -98,3 +111,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. In the unified model the default list IS the globally-active-by-default
+// set (one `defaults` key in config.yaml): a default skill is active in every
+// project AND auto-loaded on start. So this just returns that list filtered to
+// installed skills. Defaults are GLOBAL (never per-folder) and ignore a
+// project's deny rules (deny only governs active state, not auto-load).
+export function computeDefaults(installed, globalCfg) {
+  const canonByLower = new Map(installed.map(s => [String(s.name).toLowerCase(), s.name]))
+  return [...new Set((globalCfg.defaults || []).map(s => String(s).toLowerCase()))]
+    .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/paths.js

@@ -17,4 +17,6 @@ export const AGENT_GLOBALS = [
   { id: 'claude', dir: '.claude', file: 'CLAUDE.md' },
   { id: 'codex', dir: '.codex', file: 'AGENTS.md' },
   { id: 'gemini', dir: '.gemini', file: 'GEMINI.md' },
+  // pi loads global context from ~/.pi/agent/AGENTS.md (or CLAUDE.md).
+  { id: 'pi', dir: '.pi/agent', file: 'AGENTS.md' },
 ]

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)
+}