@victortomaili/skill-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- "Star the repo" call to action in `skill --help` (with the `gh repo star` command) and the README.
+
+### Planned
+- Cursor adapter (`.cursor/rules` format) for `init -g` bootstrap.
+- Per-agent hook adapters for automatic `/X` triggering (push model).
+
+## [0.1.0] - 2026-07-07
+
+### Added
+- **Central store + activation model** — skills live in `~/.skill-cli/store`;
+  agent directories stay clean.
+- **Commands:** `init [-g]`, `install`, `update`, `enable [-g]`, `disable [-g]`,
+  `list`, `show`, `cat`, `trigger`. Aliases: `ls`, `add`, `info`.
+- **Universal install sources** — `owner/repo`, GitHub/GitLab URL, git URL, local
+  path, npm package — delegated to `npx skills add` in a temp cwd (agent folders
+  untouched).
+- **Three-layer activation** — installed → enabled globally → enabled per project,
+  with `allow` winning over `deny` and case-insensitive matching throughout.
+- **Idempotent `AGENTS.md` bootstrap** — injected into `CLAUDE.md`, `AGENTS.md`,
+  `GEMINI.md` behind `BEGIN/END` markers; never duplicates, preserves existing
+  content.
+- **Pull-based `/X` triggers** — `skill trigger <keyword>` resolves to content
+  (single match), candidates (multiple), or info (none).
+- **Cross-platform** — Windows (`cmd.exe /c npx`, `CVE-2024-27980` workaround),
+  macOS, Linux.
+- **`skill.config`** per-project override: `inherit` / `deny` / `allow`.
+- **`.source` tracking** so `skill update` can re-fetch and diff (sha256 +
+  version compare); exits non-zero on failure.
+- **157 tests** (unit + CLI), network-free by default; opt-in `npm run test:e2e`
+  for the real `npx` fetch path.
+
+### Security
+- `install`/`update` destination names are sanitized (`SAFE_NAME`) — a malicious
+  frontmatter `name: ../x` cannot escape the store or `rmSync` outside it.
+- `update` case-folds skill names (consistent with all other commands).
+- 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.0...HEAD
+[0.1.0]: https://github.com/victortomaili/skill-cli/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skill-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# skill-cli
+
+> One skill store. Clean agent folders. Activate from anywhere.
+
+[![CI](https://github.com/victortomaili/skill-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/victortomaili/skill-cli/actions/workflows/ci.yml)
+[![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)
+
+**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
+directories stay **clean** — and you control which skill is active where with one
+config file.
+
+- 🗂️ **One canonical store** — `~/.skill-cli/store`. No more copies scattered across `~/.claude`, `~/.codex`, `~/.cursor`, …
+- 🧹 **Agent folders untouched** — nothing is written into agent directories.
+- 🎛️ **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.
+- 🖥️ **Cross-platform** — Windows, macOS, Linux (handles the Windows `npx` spawn quirk for you).
+- 🧪 **Well tested** — 157 unit + CLI tests, network-free by default.
+
+## ⭐ Found this useful?
+
+If skill-cli saves you time, please [give it a star ⭐](https://github.com/victortomaili/skill-cli)
+on GitHub — it helps others discover the project and keeps development going. Thank you! 💜
+
+## Installation
+
+```bash
+npm install -g @victortomaili/skill-cli
+```
+
+Requires Node.js 22+.
+
+## Quick start
+
+```bash
+# 1) one-time global setup (creates the store + bootstraps detected agents)
+skill init -g
+
+# 2) install a skill from any source
+skill install owner/repo
+
+# 3) use it — type /<trigger> in your agent, or load directly
+skill list
+skill cat <name>
+```
+
+That's it. Your agent now knows: *when the user types `/X`, run `skill trigger X`*.
+
+## How it works
+
+```
+~/.skill-cli/
+  store/<skill>/SKILL.md     ← one canonical store (skills live here)
+  config.yaml                ← global config (enabled_global)
+
+<project>/skill.config       ← per-project activation (inherit / deny / allow)
+~/.claude/CLAUDE.md          ← bootstrap block injected by `skill init -g`
+~/.codex/AGENTS.md             (idempotent — preserves your existing content)
+~/.gemini/GEMINI.md
+```
+
+Agents don't read `skill.config` directly — the CLI does. The agent only needs the
+short bootstrap block telling it to run `skill` on `/X`.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `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 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 update [name…\|--all]` | Re-fetch from source, update changed skills |
+
+Aliases: `ls` (list), `add` (install), `info` (show).
+
+## Install sources
+
+`install` delegates resolution to `npx skills`, so every format works:
+
+```
+owner/repo                                        GitHub shorthand
+https://github.com/owner/repo                     full GitHub URL
+https://github.com/owner/repo/tree/main/skills/x  path inside a repo
+https://gitlab.com/org/repo                       GitLab URL
+git@github.com:owner/repo.git                     any git URL
+./my-local-skills                                 local path
+<npm-package>                                     npm package shipping skills
+```
+
+Install runs `npx skills add` in a **temp cwd** so files land in `<tmp>/.claude/skills/`
+and are then moved into `~/.skill-cli/store/`. Your real agent directories are
+**never** written to.
+
+## Skill format
+
+Faithful to the `SKILL.md` standard (the author decides the structure):
+
+```yaml
+---
+name: deep-research
+description: Deep source-research workflow
+version: 1.2.0
+triggers: [research, deep-search]   # skill-cli-specific; powers /<trigger>
+---
+# Your instructions here
+```
+
+`triggers` is optional and skill-cli-specific. See [`examples/hello-world/SKILL.md`](examples/hello-world/SKILL.md)
+for a minimal, copy-paste template.
+
+## Activation
+
+Three layers, most-specific wins:
+
+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
+
+A project `skill.config` overrides the global set. Pure allowlist mode:
+
+```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
+```
+
+> `allow` always wins over `deny`, so `deny: ["*"]` + `allow: [X]` = "only X".
+> Matching is case-insensitive throughout.
+
+## Bootstrap
+
+`skill init -g` injects a short, idempotent block into each detected agent's global
+instruction file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`):
+
+> When the user types `/X`, run `skill trigger X`. Single match → apply the output;
+> multiple → show candidates; load each skill only once per session.
+
+It's wrapped in `<!-- BEGIN skill-cli --> … <!-- END skill-cli -->` markers, never
+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
+a different format — adapter planned. See [issue tracker](https://github.com/victortomaili/skill-cli/issues).)
+
+## Cross-platform
+
+Works on Windows, macOS, and Linux. On Windows it spawns `npx` via `cmd.exe /c`
+(the Node 20+ `CVE-2024-27980` workaround) with `shell:false` and validates the
+source against shell metacharacters, so it's safe by default.
+
+## Development
+
+```bash
+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 run test:e2e    # opt-in: real npx fetch over the network
+```
+
+Tests never touch your real `~` — they use an isolated `SKILL_CLI_HOME`. See
+[CONTRIBUTING.md](./CONTRIBUTING.md) for the project structure, how to add a command,
+and the PR checklist.
+
+## Contributing
+
+Contributions are welcome! 💜 Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and
+follow our [Code of Conduct](./CODE_OF_CONDUCT.md).
+
+- 🐛 [Report a bug](https://github.com/victortomaili/skill-cli/issues/new?template=bug_report.yml)
+- ✨ [Request a feature](https://github.com/victortomaili/skill-cli/issues/new?template=feature_request.yml)
+- 🔒 Found a security issue? See [SECURITY.md](./SECURITY.md) — report it privately, not as a public issue.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+[MIT](./LICENSE) © skill-cli contributors

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@victortomaili/skill-cli",
+  "version": "0.1.0",
+  "description": "Cross-agent skill manager — one global store, clean agent folders, activation via skill.config",
+  "license": "MIT",
+  "author": "Victor Tomaili <victor@tomaili.com>",
+  "homepage": "https://github.com/victortomaili/skill-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/victortomaili/skill-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/victortomaili/skill-cli/issues"
+  },
+  "type": "module",
+  "bin": {
+    "skill": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:e2e": "node scripts/e2e.mjs"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1",
+    "yaml": "^2.6.0"
+  },
+  "keywords": [
+    "cli",
+    "skills",
+    "skill",
+    "agent",
+    "ai",
+    "ai-agent",
+    "llm",
+    "claude",
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini",
+    "prompt-engineering",
+    "developer-tools",
+    "workflow"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import c from 'picocolors'
+import { cmdInit } from './commands/init.js'
+import { cmdList } from './commands/list.js'
+import { cmdTrigger } from './commands/trigger.js'
+import { cmdShow } from './commands/show.js'
+import { cmdCat } from './commands/cat.js'
+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 { 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('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.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('Usage (agent)')}
+  ${c.cyan('skill show')} ${c.gray('<name>')}         metadata + path + triggers
+  ${c.cyan('skill cat')} ${c.gray('<name>')}          dump content to context
+  ${c.cyan('skill trigger')} ${c.gray('<keyword>')}   /X trigger: single→content, multi→candidates
+
+${c.bold('Maintenance')}
+  ${c.cyan('skill update')} ${c.gray('[name|--all]')} refresh store from source
+
+${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')}
+
+${c.bold('★ Enjoying skill-cli?')} ${c.gray('Star the repo — it helps others find it.')}
+  ${c.cyan('gh repo star victortomaili/skill-cli')}
+  ${c.gray('or: https://github.com/victortomaili/skill-cli')}
+`
+
+const [, , cmd, ...rest] = process.argv
+
+try {
+  switch (cmd) {
+    case undefined:
+    case '-h': case '--help': case 'help':
+      console.log(HELP); break
+    case 'init': cmdInit(rest); break
+    case 'install': case 'add': cmdInstall(rest); break
+    case 'enable': cmdEnable(rest); break
+    case 'disable': cmdDisable(rest); break
+    case 'list': case 'ls': cmdList(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 '-v': case '--version':
+      console.log('skill-cli ' + VERSION); break
+    default:
+      console.error(c.red('Unknown command: ' + cmd))
+      console.error(c.gray('  skill --help'))
+      process.exit(1)
+  }
+} catch (e) {
+  console.error(c.red('Error: ') + e.message)
+  process.exit(1)
+}

package/src/commands/cat.js

@@ -0,0 +1,12 @@
+import c from 'picocolors'
+import { readSkill } from '../lib/store.js'
+
+// Dumps the skill body so it can be loaded into context.
+export function cmdCat(args) {
+  const name = args[0]
+  if (!name) { console.error(c.red('Usage: skill cat <name>')); process.exit(1) }
+  const s = readSkill(name)
+  if (!s) { console.error(c.red('Skill not found: ' + name)); process.exit(1) }
+  console.log(c.gray('<!-- skill: ' + s.name + ' -->'))
+  console.log(s.body.trim())
+}

package/src/commands/disable.js

@@ -0,0 +1,27 @@
+import c from 'picocolors'
+import { readGlobalConfig, writeGlobalConfig, readProjectConfig, writeProjectConfig } from '../lib/config.js'
+
+export function cmdDisable(args) {
+  const global = args.includes('-g') || args.includes('--global')
+  const name = args.find(a => !a.startsWith('-'))
+  if (!name) { console.error(c.red('Usage: skill disable <name> [-g]')); process.exit(1) }
+
+  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())
+    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)')))
+  } else {
+    const cwd = process.cwd()
+    const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [] }
+    const had = (cfg.allow || []).some(a => a.toLowerCase() === name.toLowerCase())
+    cfg.allow = (cfg.allow || []).filter(a => a.toLowerCase() !== name.toLowerCase())
+    writeProjectConfig(cwd, cfg)
+    console.log(had
+      ? (c.green('✓') + ' disabled in project: ' + c.bold(name))
+      : (c.gray('·') + ' not enabled in project: ' + c.bold(name) + c.gray(' (nothing to do)')))
+  }
+}

package/src/commands/enable.js

@@ -0,0 +1,31 @@
+import c from 'picocolors'
+import { readGlobalConfig, writeGlobalConfig, readProjectConfig, writeProjectConfig } from '../lib/config.js'
+import { listStore } from '../lib/store.js'
+
+export function cmdEnable(args) {
+  const global = args.includes('-g') || args.includes('--global')
+  const name = args.find(a => !a.startsWith('-'))
+  if (!name) { console.error(c.red('Usage: skill enable <name> [-g]')); process.exit(1) }
+
+  // must be installed — enabling a typo silently "succeeds" but never activates
+  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.enabled_global.some(a => a.toLowerCase() === name.toLowerCase())) {
+      cfg.enabled_global.push(name.toLowerCase()); cfg.enabled_global.sort()
+    }
+    writeGlobalConfig(cfg)
+    console.log(c.green('✓') + ' enabled globally: ' + c.bold(name) + c.gray('  (active in all projects)'))
+  } else {
+    const cwd = process.cwd()
+    const cfg = readProjectConfig(cwd) || { inherit: true, deny: [], allow: [] }
+    if (!cfg.allow.some(a => a.toLowerCase() === name.toLowerCase())) cfg.allow.push(name.toLowerCase())
+    writeProjectConfig(cwd, cfg)
+    console.log(c.green('✓') + ' enabled in project: ' + c.bold(name) + c.gray('  (' + cwd + ')'))
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import c from 'picocolors'
+import { CLI_ROOT, STORE_DIR } from '../lib/paths.js'
+import { readGlobalConfig, writeGlobalConfig, projectConfigPath, writeProjectConfig } from '../lib/config.js'
+import { injectToAllAgents } from '../lib/agents-md.js'
+
+export function cmdInit(args) {
+  const global = args.includes('-g') || args.includes('--global')
+  return global ? initGlobal() : initProject()
+}
+
+function initGlobal() {
+  fs.mkdirSync(STORE_DIR, { recursive: true })
+  const cfg = readGlobalConfig()
+  writeGlobalConfig(cfg)
+
+  console.log(c.green('✓') + ' skill-cli installed globally')
+  console.log(c.gray('  store:  ') + STORE_DIR)
+  console.log(c.gray('  config: ') + path.join(CLI_ROOT, 'config.yaml'))
+  console.log()
+  console.log(c.bold('AGENTS.md injection (idempotent):'))
+  for (const r of injectToAllAgents()) {
+    if (r.status === 'updated') console.log(c.green('  ✓ ') + r.agent + c.gray(' → ' + r.file))
+    else if (r.status === 'current') console.log(c.gray('  · ') + r.agent + c.gray(' (already set up)'))
+    else console.log(c.gray('  · ') + r.agent + c.gray(' (not found, skipped)'))
+  }
+  console.log()
+  console.log(c.cyan('Next: ') + 'skill install <source>  ' + c.gray('# e.g. vercel-labs/agent-skills'))
+}
+
+function initProject() {
+  const cwd = process.cwd()
+  const cfgPath = projectConfigPath(cwd)
+  if (!fs.existsSync(cfgPath)) {
+    writeProjectConfig(cwd, { inherit: true, deny: [], allow: [] })
+    console.log(c.green('✓') + ' created: ' + c.cyan('skill.config'))
+  } else {
+    console.log(c.yellow('·') + ' skill.config already exists')
+  }
+  console.log(c.gray('  inherit: true  → inherits globally-enabled skills'))
+  console.log(c.gray('  deny: ["*"] + allow: [...] → pure allowlist (block global, open one by one)'))
+  console.log()
+  console.log(c.cyan('Active skills: ') + 'skill list')
+}

package/src/commands/install.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import c from 'picocolors'
+import { STORE_DIR } from '../lib/paths.js'
+import { parseSkillMd } from '../lib/frontmatter.js'
+import { fetchSkillsToTemp } from '../lib/npx.js'
+import { sanitizeSkillName } from '../lib/store.js'
+
+// Local paths are resolved to absolute BEFORE switching to the temp cwd, so
+// npx skills looks them up relative to the user's cwd, not the temp dir.
+function resolveSource(source) {
+  if (/:\/\//.test(source) || source.startsWith('git@')) return source
+  if (fs.existsSync(source)) return path.resolve(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)
+  }
+
+  const resolved = resolveSource(source)
+  console.log(c.cyan('Fetching: ') + resolved)
+  console.log(c.gray('  via npx skills add (temp cwd; agent folders untouched)'))
+
+  let tmp, fetchedDir
+  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)
+  }
+
+  try {
+    fs.mkdirSync(STORE_DIR, { recursive: true })
+    const moved = []
+    const skipped = []
+    for (const entry of fs.readdirSync(fetchedDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const srcSkillDir = path.join(fetchedDir, entry.name)
+      const mdPath = path.join(srcSkillDir, 'SKILL.md')
+      let raw = entry.name
+      if (fs.existsSync(mdPath)) {
+        try {
+          const { data } = parseSkillMd(fs.readFileSync(mdPath, 'utf8'))
+          if (data.name) raw = data.name
+        } catch { /* fall back to dir name */ }
+      }
+      // S1 (path traversal): the dest name is untrusted — it comes from the
+      // fetched SKILL.md frontmatter or source dir name. `name: ../x` could
+      // otherwise write (and the preceding rmSync could delete) outside STORE_DIR.
+      // Prefer the frontmatter name when safe; else the dir name; else skip.
+      const name = sanitizeSkillName(raw) || sanitizeSkillName(entry.name)
+      if (!name) { skipped.push(entry.name); continue }
+      const dest = path.join(STORE_DIR, name)
+      const reinstalled = fs.existsSync(dest)
+      fs.rmSync(dest, { recursive: true, force: true })
+      // cpSync (not renameSync): rename fails across volumes (EXDEV: C: temp → S: store).
+      fs.cpSync(srcSkillDir, dest, { recursive: true })
+      // remember the source so `skill update` can re-fetch it later
+      fs.writeFileSync(path.join(dest, '.source'), resolved + '\n')
+      moved.push({ name, reinstalled })
+    }
+    for (const s of skipped) console.log(c.yellow('  ⚠ skipped ') + c.bold(s) + c.gray(' (not a safe skill name)'))
+
+    if (moved.length === 0) {
+      // throw (not process.exit) so the finally cleans up the temp dir
+      throw new Error('No skills moved to store.')
+    }
+    const fresh = moved.filter(m => !m.reinstalled).length
+    const re = moved.length - fresh
+    console.log(c.green(`✓ ${fresh} installed` + (re ? c.gray(` · ${re} reinstalled`) : '') + ' to store:'))
+    for (const m of moved) {
+      const mark = m.reinstalled ? c.yellow('↻') : c.green('•')
+      const tail = m.reinstalled ? c.gray('  (reinstalled)') : c.gray('  → ' + path.join(STORE_DIR, m.name))
+      console.log('  ' + mark + ' ' + c.bold(m.name) + tail)
+    }
+    console.log()
+    console.log(c.gray('Skills are passive until enabled. Activate with: ') + c.cyan('skill enable <name>') + c.gray(' or ') + c.cyan('-g'))
+  } finally {
+    if (tmp) fs.rmSync(tmp, { recursive: true, force: true })
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,38 @@
+import c from 'picocolors'
+import { listStore } from '../lib/store.js'
+import { readGlobalConfig, readProjectConfig, computeEffective } from '../lib/config.js'
+import { trunc } from '../lib/format.js'
+
+export function cmdList(_args = []) {
+  const installed = listStore()
+  const globalCfg = readGlobalConfig()
+  const projCfg = readProjectConfig()
+  const effective = computeEffective(installed, globalCfg, projCfg)
+
+  const scope = projCfg ? c.magenta(process.cwd()) : c.gray('(global)')
+  console.log(c.bold('skill list') + c.gray(' — project: ') + scope)
+  console.log()
+
+  if (installed.length === 0) {
+    console.log(c.yellow('  Store empty.') + c.gray('  First: skill install <source>'))
+    return
+  }
+
+  for (const s of installed) {
+    const active = effective.includes(s.name)
+    const mark = active ? c.green('●') : 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}`)
+    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.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 ')
+  return c.gray('-      ')
+}

package/src/commands/show.js

@@ -0,0 +1,18 @@
+import c from 'picocolors'
+import { readSkill } from '../lib/store.js'
+import { getTriggers } from '../lib/frontmatter.js'
+
+export function cmdShow(args) {
+  const name = args[0]
+  if (!name) { console.error(c.red('Usage: skill show <name>')); process.exit(1) }
+  const s = readSkill(name)
+  if (!s) { console.error(c.red('Skill not found: ' + name)); process.exit(1) }
+
+  console.log(c.bold(s.name) + c.gray('  v' + (s.data.version || '-')))
+  if (s.data.description) console.log(c.gray(s.data.description))
+  console.log()
+  console.log(c.gray('path:     ') + s.path)
+  const trg = getTriggers(s.data).map(t => '/' + t).join(', ') || '—'
+  console.log(c.gray('triggers: ') + trg)
+  console.log(c.gray('content:  ') + c.cyan('skill cat ' + s.name))
+}

package/src/commands/trigger.js

@@ -0,0 +1,46 @@
+import c from 'picocolors'
+import { listStore, readSkill } from '../lib/store.js'
+import { readGlobalConfig, readProjectConfig, computeEffective } from '../lib/config.js'
+import { normalizeTrigger } from '../lib/frontmatter.js'
+import { trunc } from '../lib/format.js'
+
+// /X trigger: keyword match across ACTIVE skills.
+//   single  → dump skill content (drops into context)
+//   multi   → candidate list (name + description); agent picks with `skill cat <name>`
+//   none    → informational
+export function cmdTrigger(args) {
+  const keyword = normalizeTrigger(args[0] || '')
+  if (!keyword) {
+    console.error(c.red('Usage: skill trigger <keyword>   (e.g. /research)'))
+    process.exit(1)
+  }
+
+  const installed = listStore()
+  const effective = computeEffective(installed, readGlobalConfig(), readProjectConfig())
+  // Search ONLY active skills — a passive skill cannot trigger.
+  const candidates = installed.filter(s => effective.includes(s.name) && s.triggers.includes(keyword))
+
+  if (candidates.length === 0) {
+    console.log(c.yellow('No active skill has the ') + c.cyan('/' + keyword) + c.yellow(' trigger.'))
+    console.log(c.gray('  Run skill list to see active skills and their triggers.'))
+    return
+  }
+
+  if (candidates.length === 1) {
+    const s = readSkill(candidates[0].name)
+    if (!s) { console.error(c.red('Skill not readable: ' + candidates[0].name)); process.exit(1) }
+    console.log(c.green('▼ skill: ') + c.bold(s.name) + c.gray('  (triggered: /' + keyword + ')'))
+    console.log(c.gray('━'.repeat(56)))
+    console.log(s.body.trim())
+    return
+  }
+
+  console.log(c.yellow('/' + keyword) + ' matched ' + c.bold(candidates.length + ' skills') + ' — pick one:')
+  console.log()
+  for (const s of candidates) {
+    console.log('  ' + c.cyan(s.name.padEnd(20)) + c.gray('  ' + trunc(s.description, 54)))
+  }
+  console.log()
+  console.log(c.gray('Pick: ') + 'skill cat <name>')
+}
+

package/src/commands/update.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import c from 'picocolors'
+import { STORE_DIR } from '../lib/paths.js'
+import { parseSkillMd } from '../lib/frontmatter.js'
+import { listStore } from '../lib/store.js'
+import { fetchSkillsToTemp } from '../lib/npx.js'
+import { pad } from '../lib/format.js'
+
+// Re-fetch each skill from its recorded source and update the store if changed.
+//   skill update              update all skills in the store
+//   skill update <name>...    update specific skills
+//   skill update --all        same as no args (explicit)
+export function cmdUpdate(args) {
+  const installed = listStore()
+  const byLower = new Map(installed.map(s => [s.name.toLowerCase(), s.name]))
+  const explicit = args.filter(a => !a.startsWith('-'))
+
+  let targets = []
+  let unknown = 0
+  if (explicit.length) {
+    // B1: case-fold to the canonical installed name (every other command does).
+    // A side benefit: an unknown name like `../x` can't reach path.join(STORE_DIR,
+    // name), closing the latent traversal surface in `skill update <name>`.
+    for (const a of explicit) {
+      const canon = byLower.get(a.toLowerCase())
+      if (canon) targets.push(canon)
+      else { console.log(c.red('  ✗ ' + pad(a)) + c.red('not installed')); unknown++ }
+    }
+  } else {
+    targets = installed.map(s => s.name)
+  }
+
+  if (targets.length === 0 && unknown === 0) {
+    console.log(c.yellow('Store empty. Nothing to update.'))
+    return
+  }
+
+  console.log(c.bold(`Updating ${targets.length} skill(s)…`) + c.gray('  (re-fetch from source)'))
+  console.log()
+
+  const counts = { updated: 0, current: 0, failed: 0, nosource: 0 }
+  counts.failed += unknown
+  for (const name of targets) counts[updateOne(name)]++
+
+  console.log()
+  console.log(c.gray(`  ${counts.updated} updated · ${counts.current} up to date · ${counts.failed} failed · ${counts.nosource} no source`))
+  // signal failure to callers/scripts: a non-zero exit if any fetch failed, so
+  // `skill update && deploy` won't silently proceed on a broken source.
+  if (counts.failed > 0) process.exit(1)
+}
+
+function updateOne(name) {
+  const skillPath = path.join(STORE_DIR, name)
+  if (!fs.existsSync(skillPath)) {
+    console.log(c.red('  ✗ ' + pad(name)) + c.red('not installed'))
+    return 'failed'
+  }
+  const sourceFile = path.join(skillPath, '.source')
+  if (!fs.existsSync(sourceFile)) {
+    console.log(c.gray('  · ' + pad(name)) + c.gray('source unknown — reinstall: skill install <source>'))
+    return 'nosource'
+  }
+  const source = fs.readFileSync(sourceFile, 'utf8').trim()
+
+  let tmp, fetchedDir
+  try {
+    ({ tmp, fetchedDir } = fetchSkillsToTemp(source))
+  } catch (e) {
+    console.log(c.red('  ✗ ' + pad(name)) + c.red((e.message || '').split('\n')[0]))
+    return 'failed'
+  }
+
+  try {
+    const newDir = resolveFetched(fetchedDir, name)
+    if (!newDir) throw new Error('skill not found in fetched source')
+    const newSkillDir = path.join(fetchedDir, newDir.name)
+
+    const oldVer = getVer(skillPath)
+    const newVer = getVer(newSkillDir)
+
+    if (hashDir(skillPath) === hashDir(newSkillDir)) {
+      console.log(c.gray('  ✓ ' + pad(name)) + c.gray('up to date'))
+      return 'current'
+    }
+    // replace content, preserve .source
+    fs.rmSync(skillPath, { recursive: true, force: true })
+    fs.cpSync(newSkillDir, skillPath, { recursive: true })
+    fs.writeFileSync(path.join(skillPath, '.source'), source + '\n')
+    const verInfo = oldVer !== newVer ? c.green(`${oldVer} → ${newVer}`) : c.gray('content changed')
+    console.log(c.green('  ↑ ') + c.bold(pad(name)) + verInfo)
+    return 'updated'
+  } catch (e) {
+    console.log(c.red('  ✗ ' + pad(name)) + c.red((e.message || '').split('\n')[0]))
+    return 'failed'
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+// find the fetched skill dir by name (dir name or SKILL.md name field), else single
+function resolveFetched(fetchedDir, name) {
+  const entries = fs.readdirSync(fetchedDir, { withFileTypes: true }).filter(e => e.isDirectory())
+  const byDir = entries.find(e => e.name === name)
+  if (byDir) return byDir
+  for (const e of entries) {
+    const md = path.join(fetchedDir, e.name, 'SKILL.md')
+    if (fs.existsSync(md)) {
+      try {
+        const { data } = parseSkillMd(fs.readFileSync(md, 'utf8'))
+        if (data.name === name) return e
+      } catch {}
+    }
+  }
+  // Not found by dir name or SKILL.md name field. Do NOT guess — the previous
+  // single-entry fallback could silently replace a skill with a different one if
+  // the source had changed which skill it ships. Fail loud so the user notices.
+  return null
+}
+
+// sha256 over all files in dir (excluding our own .source), sorted for determinism
+function hashDir(dir) {
+  const h = crypto.createHash('sha256')
+  if (!fs.existsSync(dir)) return '0'
+  const files = []
+  function walk(d) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.name === '.source') continue
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else files.push(p)
+    }
+  }
+  walk(dir)
+  files.sort()
+  for (const f of files) {
+    h.update(f.slice(dir.length))
+    try { h.update(fs.readFileSync(f)) } catch {}
+  }
+  return h.digest('hex')
+}
+
+function getVer(dir) {
+  const md = path.join(dir, 'SKILL.md')
+  if (!fs.existsSync(md)) return '?'
+  try { const { data } = parseSkillMd(fs.readFileSync(md, 'utf8')); return data.version || '?' } catch { return '?' }
+}

package/src/lib/agents-md.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { HOME, AGENT_GLOBALS } from './paths.js'
+
+const BEGIN = '<!-- BEGIN skill-cli -->'
+const END = '<!-- END skill-cli -->'
+
+// Global instruction block — injected into each agent's global instruction file.
+// Kept short (~140 words) so it doesn't bloat agent context on every session.
+export const AGENTS_BLOCK = `## skill-cli
+
+This machine uses the \`skill\` command to manage skills (instruction / workflow
+packages). Skills live in a single global store (\`~/.skill-cli/store\`) and are
+NOT copied into agent directories (\`~/.claude\`, \`~/.codex\`, etc.) — so they
+won't appear here.
+
+Usage:
+- \`skill list\` — skills installed and active in the current project
+- \`skill show <name>\` — skill summary (path, triggers, version)
+- \`skill cat <name>\` — load skill content into context
+
+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>\`.
+- Load each skill only ONCE per session (avoid re-injecting).
+`
+
+export function injectBlock(content) {
+  const wrapped = `${BEGIN}\n${AGENTS_BLOCK}\n${END}`
+  if (content.includes(BEGIN)) {
+    return content.replace(new RegExp(`${BEGIN}[\\s\\S]*?${END}`), wrapped)
+  }
+  return (content ? content.replace(/\n*$/, '') + '\n\n' : '') + wrapped + '\n'
+}
+
+export function injectToAgentGlobal(agent) {
+  const dir = path.join(HOME, agent.dir)
+  if (!fs.existsSync(dir)) return null
+  const file = path.join(dir, agent.file)
+  let content = ''
+  try { content = fs.readFileSync(file, 'utf8') } catch {}
+  const next = injectBlock(content)
+  // B4: only rewrite + claim "updated" when the block actually changed. On an
+  // idempotent re-run (block already present & identical) report "current" and
+  // leave the file untouched (preserves mtime, avoids needless rewrites).
+  const status = content.includes(BEGIN) ? (next === content ? 'current' : 'updated') : 'updated'
+  if (next !== content) fs.writeFileSync(file, next, 'utf8')
+  return { file, status }
+}
+
+export function injectToAllAgents() {
+  return AGENT_GLOBALS.map(agent => {
+    const r = injectToAgentGlobal(agent)
+    return r
+      ? { agent: agent.id, file: r.file, status: r.status }
+      : { agent: agent.id, file: null, status: 'agent-not-found' }
+  })
+}

package/src/lib/config.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import yaml from 'yaml'
+import { CLI_ROOT, GLOBAL_CONFIG, PROJECT_CONFIG, STORE_DIR } from './paths.js'
+
+const DEFAULT_GLOBAL = {
+  version: 1,
+  store: STORE_DIR,
+  enabled_global: [],
+}
+
+export function readGlobalConfig() {
+  let raw
+  try { raw = fs.readFileSync(GLOBAL_CONFIG, 'utf8') } catch { return { ...DEFAULT_GLOBAL } }
+  let parsed
+  try { parsed = yaml.parse(raw) } catch (e) {
+    process.stderr.write('skill-cli config: parse error (' + (e.message || e) + ') — using defaults\n')
+    return { ...DEFAULT_GLOBAL }
+  }
+  return { ...DEFAULT_GLOBAL, ...(parsed || {}) }
+}
+
+export function writeGlobalConfig(cfg) {
+  fs.mkdirSync(CLI_ROOT, { recursive: true })
+  // B2: write only the known schema, not arbitrary pass-through keys. readGlobalConfig
+  // merges parsed-over-defaults, which would otherwise round-trip dead keys (e.g.
+  // the removed `default_agents`) back into the file forever.
+  const out = {
+    version: cfg.version ?? 1,
+    store: cfg.store ?? STORE_DIR,
+    enabled_global: cfg.enabled_global || [],
+  }
+  fs.writeFileSync(GLOBAL_CONFIG, yaml.stringify(out), 'utf8')
+}
+
+export function projectConfigPath(cwd = process.cwd()) {
+  return path.join(cwd, PROJECT_CONFIG)
+}
+
+// Returns null when no project config exists. A malformed YAML is reported on
+// stderr (rather than silently falling back to global behavior).
+export function readProjectConfig(cwd = process.cwd()) {
+  let raw
+  try { raw = fs.readFileSync(projectConfigPath(cwd), 'utf8') } catch { return null }
+  let parsed
+  try { parsed = yaml.parse(raw) } catch (e) {
+    process.stderr.write('skill.config: parse error (' + (e.message || e) + ') — using global behavior\n')
+    return null
+  }
+  return { inherit: true, deny: [], allow: [], ...(parsed || {}) }
+}
+
+export function writeProjectConfig(cwd, cfg) {
+  // B2: normalize to the known schema on write (drops stale/junk keys).
+  const out = {
+    inherit: cfg.inherit !== false,
+    deny: cfg.deny || [],
+    allow: cfg.allow || [],
+  }
+  fs.writeFileSync(projectConfigPath(cwd), yaml.stringify(out), 'utf8')
+}
+
+// Simple glob: * → any chars, ? → single char. Pattern length is capped to guard
+// against ReDoS on user-supplied deny patterns.
+function globMatch(pattern, name) {
+  if (pattern === '*') return true
+  if (pattern.length > 200) return false
+  const re = new RegExp(
+    '^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$',
+    'i'
+  )
+  return re.test(name)
+}
+
+// Effective skills, returned as CANONICAL names (from the installed store). allow
+// always wins over deny, so `deny: ["*"]` + `allow: [X]` = "only X". Matching is
+// case-insensitive throughout — the user may type "React-BP" while the skill is "react-bp".
+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 || []))
+      .map(s => String(s).toLowerCase())
+  )
+  if (projCfg) {
+    const allowLower = new Set((projCfg.allow || []).map(a => String(a).toLowerCase()))
+    for (const d of (projCfg.deny || [])) {
+      for (const name of [...enabled]) {
+        if (allowLower.has(name)) continue
+        if (d.includes('*') ? globMatch(d, name) : String(d).toLowerCase() === name) {
+          enabled.delete(name)
+        }
+      }
+    }
+    for (const a of (projCfg.allow || [])) enabled.add(String(a).toLowerCase())
+  }
+  return [...enabled]
+    .filter(n => canonByLower.has(n))
+    .map(n => canonByLower.get(n))
+    .sort()
+}

package/src/lib/format.js

@@ -0,0 +1,12 @@
+// Shared output helpers.
+
+// Truncate to n chars, collapsing any newlines to spaces (keeps single-line output).
+export function trunc(s, n) {
+  s = String(s ?? '').replace(/[\r\n]+/g, ' ').trim()
+  return s.length > n ? s.slice(0, n - 1) + '…' : s
+}
+
+// Left-pad a string to a fixed column width.
+export function pad(s, n = 22) {
+  return (String(s) + ' '.repeat(n)).slice(0, n)
+}

package/src/lib/frontmatter.js

@@ -0,0 +1,27 @@
+import yaml from 'yaml'
+
+// SKILL.md = YAML frontmatter + markdown body. Faithful to the npx skills standard.
+export function parseSkillMd(content) {
+  // strip a leading UTF-8 BOM — Windows editors often save with one, and it would
+  // break the `^---` frontmatter match (silently dropping name/triggers/version).
+  if (content.charCodeAt(0) === 0xFEFF) content = content.slice(1)
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+  if (!m) return { data: {}, body: content }
+  let data = {}
+  try { data = yaml.parse(m[1]) || {} } catch { /* malformed frontmatter → empty */ }
+  return { data, body: m[2] || '' }
+}
+
+// "/Research", "Research", "research" → "research". Trim BEFORE stripping the
+// leading slash, so comma-split entries like " /code" also normalize.
+export function normalizeTrigger(t) {
+  return String(t).trim().replace(/^\/+/, '').toLowerCase()
+}
+
+// frontmatter.triggers → normalized array
+export function getTriggers(data) {
+  const t = data.triggers
+  if (Array.isArray(t)) return t.map(normalizeTrigger).filter(Boolean)
+  if (typeof t === 'string') return t.split(',').map(normalizeTrigger).filter(Boolean)
+  return []
+}

package/src/lib/npx.js

@@ -0,0 +1,104 @@
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+// Fetch skill(s) from `source` into a TEMP cwd via `npx skills add --copy`.
+// Output lands in <tmp>/.claude/skills/ — never in real agent dirs. The caller
+// owns the returned `tmp` and MUST rmSync(tmp, {recursive,force}) in a finally.
+//
+// Assemble the spawn target for `npx skills add` so it runs safely on every
+// platform. Pure + exported so the per-platform branching is unit-testable.
+//
+// Windows (process.platform === 'win32', incl. Git Bash / Cygwin / MSYS — Node
+// still reports 'win32'): Node 20+ (CVE-2024-27980) refuses to spawn .cmd/.bat
+// files such as npx.cmd with shell:false. We spawn cmd.exe (a real .exe) and let
+// it resolve npx via `cmd.exe /c npx ...`.
+//
+// Linux / macOS / WSL: npx is a real executable on PATH (ships with npm/node),
+// spawned directly.
+//
+// On ALL platforms we use shell:false with an args array, so the source is passed
+// 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.
+export function buildNpxSpawn(source, platform = process.platform) {
+  const base = ['-y', 'skills', 'add', source, '--copy', '--agent', 'claude-code', '--skill', '*', '-y']
+  return platform === 'win32'
+    ? { cmd: 'cmd.exe', args: ['/c', 'npx', ...base] }
+    : { cmd: 'npx', args: base }
+}
+
+// Fetch skill(s) from `source` into a TEMP cwd via `npx skills add --copy`.
+// Output lands in <tmp>/.claude/skills/ — never in real agent dirs. The caller
+// owns the returned `tmp` and MUST rmSync(tmp, {recursive,force}) in a finally.
+export function fetchSkillsToTemp(source) {
+  // Test seam: when SKILL_CLI_FETCH_FIXTURE is set, copy a local fixture tree
+  // instead of spawning npx. Lets install/update run with zero network.
+  // Production never sets this env var.
+  const fixture = process.env.SKILL_CLI_FETCH_FIXTURE
+  if (fixture) return fetchFromFixture(fixture)
+
+  const safe = String(source ?? '').trim()
+  if (!safe) throw new Error('empty source')
+  if (/[\r\n]/.test(safe)) throw new Error('source must be a single line')
+  // B5: defense-in-depth on Windows. The source reaches `cmd.exe /c npx … <source>`;
+  // cmd.exe parses shell metacharacters even though we spawn with shell:false
+  // (cmd.exe IS a shell). Real sources (owner/repo, URL, git URL, npm name, local
+  // path) never contain these, so reject loudly rather than risk cmd interpreting.
+  if (process.platform === 'win32' && /[&|<>^]/.test(safe)) {
+    throw new Error('source contains Windows shell metacharacters (& | < > ^) — use a path/URL without them')
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-cli-'))
+  const { cmd, args } = buildNpxSpawn(safe)
+
+  try {
+    execFileSync(cmd, args, {
+      cwd: tmp,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      shell: false,
+      timeout: 180000, // npx first-run + git clone can be slow; don't hang forever
+      env: { ...process.env, CI: '1' },
+    })
+  } catch (e) {
+    fs.rmSync(tmp, { recursive: true, force: true })
+    let msg
+    if (e.code === 'ENOENT') {
+      // npx/node not on PATH — same message on every platform
+      msg = 'npx not found on PATH — is Node.js (with npm) installed?'
+    } else {
+      const timedOut = e.signal === 'SIGTERM' || e.code === 'ETIMEDOUT'
+      const tail = timedOut ? '' : ((e.stderr || e.stdout) || '').toString().trim().split('\n').pop()
+      msg = timedOut
+        ? 'fetch timed out after 3 min (network too slow or source too large?)'
+        : 'fetch failed: ' + (tail || e.message)
+    }
+    const err = new Error(msg)
+    err.cause = e
+    throw err
+  }
+
+  const fetchedDir = path.join(tmp, '.claude', 'skills')
+  if (!fs.existsSync(fetchedDir)) {
+    fs.rmSync(tmp, { recursive: true, force: true })
+    throw new Error('no skills found in source after fetch')
+  }
+  return { tmp, fetchedDir }
+}
+
+// Fixture-backed fetch. The fixture is a dir of skill dirs — the same layout npx
+// produces under .claude/skills/. Mirror it into a temp so install/update behave
+// identically to the real path, with no network.
+function fetchFromFixture(fixture) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-cli-'))
+  const fetchedDir = path.join(tmp, '.claude', 'skills')
+  fs.mkdirSync(fetchedDir, { recursive: true })
+  if (fs.existsSync(fixture)) {
+    for (const entry of fs.readdirSync(fixture, { withFileTypes: true })) {
+      if (entry.isDirectory()) fs.cpSync(path.join(fixture, entry.name), path.join(fetchedDir, entry.name), { recursive: true })
+    }
+  }
+  return { tmp, fetchedDir }
+}

package/src/lib/paths.js

@@ -0,0 +1,20 @@
+import os from 'node:os'
+import path from 'node:path'
+
+// SKILL_CLI_HOME overrides ALL home references — safe for testing. In production
+// this is the real os.homedir(); ~/.skill-cli, ~/.claude, etc. all derive from it.
+export const HOME = process.env.SKILL_CLI_HOME || os.homedir()
+
+export const CLI_ROOT = path.join(HOME, '.skill-cli')
+export const STORE_DIR = path.join(CLI_ROOT, 'store')
+export const GLOBAL_CONFIG = path.join(CLI_ROOT, 'config.yaml')
+
+export const PROJECT_CONFIG = 'skill.config'
+
+// Each agent's global instruction file. `skill init -g` injects an idempotent
+// block into these. (Cursor uses .cursor/rules with a different format — adapter later.)
+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' },
+]

package/src/lib/store.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { STORE_DIR } from './paths.js'
+import { parseSkillMd, getTriggers } from './frontmatter.js'
+
+export function skillDir(name) { return path.join(STORE_DIR, name) }
+export function skillMdPath(name) { return path.join(skillDir(name), 'SKILL.md') }
+
+// Scan the store for all skills (name, description, version, triggers, path)
+export function listStore() {
+  if (!fs.existsSync(STORE_DIR)) return []
+  const out = []
+  for (const entry of fs.readdirSync(STORE_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const md = skillMdPath(entry.name)
+    if (!fs.existsSync(md)) continue
+    try {
+      const { data } = parseSkillMd(fs.readFileSync(md, 'utf8'))
+      out.push({
+        name: data.name || entry.name,
+        dir: entry.name,
+        description: data.description || '',
+        version: data.version || '-',
+        triggers: getTriggers(data),
+        path: md,
+      })
+    } catch { /* broken skill → skip */ }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+// A skill name is a plain identifier (alnum/._-, starting alnum). Rejecting path
+// separators and ".." closes a path-traversal surface: `skill cat ../../x` can't
+// escape STORE_DIR via the dir-name path. Exported so install/update can reuse it
+// on the WRITE path — the dangerous one: a malicious frontmatter `name: ../x`
+// could otherwise rmSync/cpSync outside STORE_DIR.
+export const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+// Returns a safe skill name (alnum/._- only, no "..", resolving strictly inside
+// STORE_DIR) or null if `name` could escape the store. Call before joining any
+// untrusted name (frontmatter `name`, fetched dir name) onto STORE_DIR.
+export function sanitizeSkillName(name) {
+  const n = String(name ?? '').trim()
+  if (!SAFE_NAME.test(n) || n.includes('..')) return null
+  const root = path.resolve(STORE_DIR)
+  const dest = path.resolve(STORE_DIR, n)
+  if (dest !== root && !dest.startsWith(root + path.sep)) return null
+  return n
+}
+
+export function readSkill(nameOrDir) {
+  const n = String(nameOrDir)
+  let md = SAFE_NAME.test(n) && !n.includes('..') && fs.existsSync(skillMdPath(n)) ? skillMdPath(n) : null
+  if (!md) {
+    const hit = listStore().find(s => s.name.toLowerCase() === n.toLowerCase())
+    if (!hit) return null
+    md = hit.path
+  }
+  const { data, body } = parseSkillMd(fs.readFileSync(md, 'utf8'))
+  return { name: data.name || n, data, body, path: md }
+}

package/src/lib/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+// Single source of truth for the version — read from package.json so it never drifts.
+const here = path.dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(path.join(here, '..', '..', 'package.json'), 'utf8'))
+export const VERSION = pkg.version