cc-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,165 @@
+# cc-skills
+
+[![npm version](https://img.shields.io/npm/v/cc-skills.svg)](https://www.npmjs.com/package/cc-skills)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/cc-skills.svg)](https://nodejs.org)
+
+A thin wrapper around `npx skills add` for **CC-MIRROR** Claude Code instances.
+
+It discovers one or more CC-MIRROR variants, sets `CLAUDE_CONFIG_DIR` to the target instance's `config/` directory, and then delegates the actual install to `npx skills add`.
+
+[中文文档](./README_CN.md)
+
+## Features
+
+- **Multi-instance support** - Install skills to one or more CC-MIRROR instances
+- **Automatic discovery** - Detects CC-MIRROR instances automatically
+- **Zero dependencies** - Uses only Node.js built-in modules
+- **Dry-run mode** - Preview commands before execution
+- **Graceful fallback** - Works even without cc-mirror CLI
+
+## Why this exists
+
+`skills` already knows how to install into a Claude Code config directory when `CLAUDE_CONFIG_DIR` is set.
+
+What this package adds is only the **instance orchestration layer**:
+
+- Discover CC-MIRROR instances
+- Target one instance or all instances
+- Loop over targets
+- Set `CLAUDE_CONFIG_DIR` per instance
+- Forward the real install to `npx skills add`
+
+## Installation
+
+Run directly with `npx`:
+
+```bash
+npx cc-skills instances
+npx cc-skills add better-auth/skills --instance mclaude-auth --copy -y
+```
+
+Or install globally:
+
+```bash
+npm install -g cc-skills
+cc-skills instances
+cc-skills add better-auth/skills --all-instances --skill "*" --copy -y
+```
+
+## Usage
+
+### `instances` - List CC-MIRROR instances
+
+```bash
+cc-skills instances
+cc-skills instances --json
+cc-skills instances --cc-root ~/.cc-mirror
+```
+
+### `add` - Install skills to instances
+
+```bash
+cc-skills add <source> (--instance <name> | --all-instances) [options]
+```
+
+**Examples:**
+
+```bash
+# Single instance
+cc-skills add better-auth/skills --instance mclaude-auth --copy -y
+
+# Multiple named instances
+cc-skills add better-auth/skills --instance mclaude-auth --instance mclaude-security --copy -y
+
+# All instances
+cc-skills add better-auth/skills --all-instances --skill "*" --copy -y
+
+# Dry run (preview without executing)
+cc-skills add better-auth/skills --instance mclaude-auth --dry-run --copy -y
+```
+
+## Options
+
+### Wrapper options (handled by cc-skills)
+
+| Option | Description |
+|--------|-------------|
+| `-i, --instance <name>` | Target a specific CC-MIRROR instance (repeatable) |
+| `--all-instances` | Target all discovered instances |
+| `--cc-root <path>` | Custom CC-MIRROR root directory |
+| `--cc-bin-dir <path>` | Forwarded to `cc-mirror list` |
+| `--dry-run` | Print commands without executing them |
+| `--fail-fast` | Stop after the first failed install |
+| `--verbose` | Print the underlying `npx` commands |
+
+### Forwarded options (passed to `npx skills add`)
+
+| Option | Description |
+|--------|-------------|
+| `--copy` | Copy files instead of symlinking |
+| `-y` | Skip confirmation prompts |
+| `--skill <name>` | Install specific skill (use `*` for all) |
+| `--list` | List available skills in source |
+
+## Important Behavior
+
+This wrapper always injects:
+
+```bash
+-g -a claude-code
+```
+
+This means every install is done in the target instance's global Claude Code scope.
+
+## Do not use `skills --all`
+
+The `skills --all` flag means **all skills to all agents**, which is broader than this wrapper's scope.
+
+If you want all skills from a repository, use:
+
+```bash
+cc-skills add owner/repo --all-instances --skill "*" --copy -y
+```
+
+## How It Works
+
+**Discovery phase:**
+
+```bash
+npx -y cc-mirror list --json
+```
+
+**Installation phase (per instance):**
+
+```bash
+CLAUDE_CONFIG_DIR="~/.cc-mirror/<instance>/config" \
+npx -y skills add <source> -g -a claude-code ...
+```
+
+## Fallback Behavior
+
+If `cc-mirror list --json` is unavailable or fails, the wrapper falls back to scanning the CC-MIRROR root directory and reading `variant.json` / `config/` directly.
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Run CLI locally
+node bin/cc-skills.js help
+
+# Create local tarball
+npm run pack:local
+```
+
+## Publishing
+
+```bash
+npm publish
+```
+
+## License
+
+[MIT](./LICENSE)

package/README_CN.md

@@ -0,0 +1,165 @@
+# cc-skills
+
+[![npm version](https://img.shields.io/npm/v/cc-skills.svg)](https://www.npmjs.com/package/cc-skills)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/cc-skills.svg)](https://nodejs.org)
+
+**CC-MIRROR** Claude Code 实例的 `npx skills add` 轻量封装工具。
+
+它可以发现一个或多个 CC-MIRROR 变体，将 `CLAUDE_CONFIG_DIR` 设置为目标实例的 `config/` 目录，然后将实际安装委托给 `npx skills add`。
+
+[English](./README.md)
+
+## 特性
+
+- **多实例支持** - 将技能安装到一个或多个 CC-MIRROR 实例
+- **自动发现** - 自动检测 CC-MIRROR 实例
+- **零依赖** - 仅使用 Node.js 内置模块
+- **试运行模式** - 执行前预览命令
+- **优雅降级** - 即使没有 cc-mirror CLI 也能工作
+
+## 为什么需要这个工具
+
+`skills` 已经知道如何在设置 `CLAUDE_CONFIG_DIR` 时安装到 Claude Code 配置目录。
+
+本工具仅添加了**实例编排层**：
+
+- 发现 CC-MIRROR 实例
+- 定位单个或所有实例
+- 遍历目标实例
+- 为每个实例设置 `CLAUDE_CONFIG_DIR`
+- 将实际安装转发给 `npx skills add`
+
+## 安装
+
+直接使用 `npx` 运行：
+
+```bash
+npx cc-skills instances
+npx cc-skills add better-auth/skills --instance mclaude-auth --copy -y
+```
+
+或全局安装：
+
+```bash
+npm install -g cc-skills
+cc-skills instances
+cc-skills add better-auth/skills --all-instances --skill "*" --copy -y
+```
+
+## 使用方法
+
+### `instances` - 列出 CC-MIRROR 实例
+
+```bash
+cc-skills instances
+cc-skills instances --json
+cc-skills instances --cc-root ~/.cc-mirror
+```
+
+### `add` - 向实例安装技能
+
+```bash
+cc-skills add <source> (--instance <name> | --all-instances) [选项]
+```
+
+**示例：**
+
+```bash
+# 单个实例
+cc-skills add better-auth/skills --instance mclaude-auth --copy -y
+
+# 多个指定实例
+cc-skills add better-auth/skills --instance mclaude-auth --instance mclaude-security --copy -y
+
+# 所有实例
+cc-skills add better-auth/skills --all-instances --skill "*" --copy -y
+
+# 试运行（预览而不执行）
+cc-skills add better-auth/skills --instance mclaude-auth --dry-run --copy -y
+```
+
+## 选项
+
+### 封装工具选项（由 cc-skills 处理）
+
+| 选项 | 描述 |
+|------|------|
+| `-i, --instance <name>` | 定位特定的 CC-MIRROR 实例（可重复使用） |
+| `--all-instances` | 定位所有已发现的实例 |
+| `--cc-root <path>` | 自定义 CC-MIRROR 根目录 |
+| `--cc-bin-dir <path>` | 转发给 `cc-mirror list` |
+| `--dry-run` | 仅打印命令，不执行 |
+| `--fail-fast` | 首次安装失败后停止 |
+| `--verbose` | 打印底层的 `npx` 命令 |
+
+### 转发选项（传递给 `npx skills add`）
+
+| 选项 | 描述 |
+|------|------|
+| `--copy` | 复制文件而非创建符号链接 |
+| `-y` | 跳过确认提示 |
+| `--skill <name>` | 安装特定技能（使用 `*` 表示全部） |
+| `--list` | 列出源中可用的技能 |
+
+## 重要行为
+
+此封装工具始终会注入：
+
+```bash
+-g -a claude-code
+```
+
+这意味着每次安装都在目标实例的全局 Claude Code 范围内进行。
+
+## 不要使用 `skills --all`
+
+`skills --all` 标志意味着**所有技能安装到所有代理**，这超出了本工具的范围。
+
+如果你想要仓库中的所有技能，请使用：
+
+```bash
+cc-skills add owner/repo --all-instances --skill "*" --copy -y
+```
+
+## 工作原理
+
+**发现阶段：**
+
+```bash
+npx -y cc-mirror list --json
+```
+
+**安装阶段（每个实例）：**
+
+```bash
+CLAUDE_CONFIG_DIR="~/.cc-mirror/<instance>/config" \
+npx -y skills add <source> -g -a claude-code ...
+```
+
+## 降级行为
+
+如果 `cc-mirror list --json` 不可用或失败，封装工具会降级为扫描 CC-MIRROR 根目录并直接读取 `variant.json` / `config/`。
+
+## 开发
+
+```bash
+# 运行测试
+npm test
+
+# 本地运行 CLI
+node bin/cc-skills.js help
+
+# 创建本地打包文件
+npm run pack:local
+```
+
+## 发布
+
+```bash
+npm publish
+```
+
+## 许可证
+
+[MIT](./LICENSE)

package/bin/cc-skills.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+const { main } = require('../src/cli');
+
+try {
+  const exitCode = main(process.argv.slice(2));
+  if (typeof exitCode === 'number' && exitCode !== 0) {
+    process.exitCode = exitCode;
+  }
+} catch (error) {
+  const message = error && error.message ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "cc-skills",
+  "version": "0.1.0",
+  "description": "Thin wrapper around `npx skills add` that installs skills into one or more CC-MIRROR Claude Code instances by setting CLAUDE_CONFIG_DIR per instance.",
+  "license": "MIT",
+  "author": "Lyon <lyon.liang12@gmail.com>",
+  "type": "commonjs",
+  "bin": {
+    "cc-skills": "bin/cc-skills.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "README_CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "cc-mirror",
+    "claude-code",
+    "skills",
+    "agent-skills",
+    "wrapper",
+    "claude_config_dir",
+    "cli"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/cc-skills.js",
+    "pack:local": "npm pack"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1WorldCapture/cc-skills.git"
+  },
+  "homepage": "https://github.com/1WorldCapture/cc-skills#readme",
+  "bugs": {
+    "url": "https://github.com/1WorldCapture/cc-skills/issues"
+  }
+}

package/src/cli.js

@@ -0,0 +1,238 @@
+const path = require('node:path');
+const pkg = require(path.join(__dirname, '..', 'package.json'));
+const {
+  NPX_BIN,
+  buildSkillsAddNpxArgs,
+  discoverInstances,
+  formatCommand,
+  hasListFlag,
+  normalizeSkillsAddArgs,
+  parseAddArgs,
+  parseInstancesArgs,
+  runCommand,
+  selectInstances,
+  summarizeResults,
+} = require('./lib');
+
+function printMainHelp() {
+  console.log(`
+${pkg.name} v${pkg.version}
+
+Thin wrapper around \`npx skills add\` for CC-MIRROR Claude Code instances.
+
+Usage:
+  cc-skills add <source> (--instance <name> | --all-instances) [skills add args...]
+  cc-skills instances [--json]
+  cc-skills help [command]
+
+Commands:
+  add         Install one skill package into one or more CC-MIRROR instances
+  instances   List discovered CC-MIRROR instances
+  help        Show help
+
+Global examples:
+  cc-skills instances
+  cc-skills add better-auth/skills --instance mclaude-auth --copy -y
+  cc-skills add better-auth/skills --all-instances --skill "*" --copy -y
+
+Notes:
+  - This wrapper always targets Claude Code and forces global install mode.
+  - Internally it calls: npx -y cc-mirror list --json
+  - Then, per instance, it calls: npx -y skills add <source> -g -a claude-code ...
+  - Do not pass \`skills --all\`; use \`--skill "*"\` instead.
+`);
+}
+
+function printInstancesHelp() {
+  console.log(`
+Usage:
+  cc-skills instances [options]
+
+Options:
+  --cc-root <path>      Custom CC-MIRROR root (default: ~/.cc-mirror)
+  --cc-bin-dir <path>   Forward a custom --bin-dir to cc-mirror list
+  --json                Print raw JSON
+  --verbose             Print the underlying cc-mirror command
+  -h, --help            Show this help
+`);
+}
+
+function printAddHelp() {
+  console.log(`
+Usage:
+  cc-skills add <source> [wrapper options] [skills add args...]
+
+Wrapper options:
+  -i, --instance <name>   Target a specific CC-MIRROR instance (repeatable)
+  --all-instances         Target every discovered CC-MIRROR instance
+  --cc-root <path>        Custom CC-MIRROR root (default: ~/.cc-mirror)
+  --cc-bin-dir <path>     Forward a custom --bin-dir to cc-mirror list
+  --dry-run               Print commands without executing them
+  --fail-fast             Stop after the first failed install
+  --verbose               Print underlying npx commands
+  -h, --help              Show this help
+
+Forwarded to \`skills add\`:
+  Any unrecognized args are passed through to \`npx skills add\`.
+  Common examples: --copy, -y, --skill <name>, --list
+
+Examples:
+  cc-skills add better-auth/skills --instance mclaude-auth --copy -y
+  cc-skills add better-auth/skills --instance mclaude-auth --skill organization --copy -y
+  cc-skills add better-auth/skills --all-instances --skill "*" --copy -y
+  cc-skills add better-auth/skills --instance mclaude-auth --dry-run --copy -y
+
+Important:
+  - The wrapper injects \`-g -a claude-code\` automatically.
+  - \`skills --all\` is intentionally blocked because it installs to all agents.
+`);
+}
+
+function printInstances(instances, json) {
+  if (json) {
+    console.log(JSON.stringify(instances, null, 2));
+    return;
+  }
+
+  if (instances.length === 0) {
+    console.log('No CC-MIRROR instances found.');
+    return;
+  }
+
+  for (const instance of instances) {
+    const provider = instance.provider || 'unknown';
+    console.log(`${instance.name}\t${provider}\t${instance.configDir}`);
+  }
+}
+
+function handleInstances(argv) {
+  const options = parseInstancesArgs(argv);
+  if (options.help) {
+    printInstancesHelp();
+    return 0;
+  }
+
+  const instances = discoverInstances(options);
+  printInstances(instances, options.json);
+  return 0;
+}
+
+function handleAdd(argv) {
+  const options = parseAddArgs(argv);
+  if (options.help) {
+    printAddHelp();
+    return 0;
+  }
+
+  const discovered = discoverInstances({
+    ccRoot: options.ccRoot,
+    ccBinDir: options.ccBinDir,
+    verbose: options.verbose,
+  });
+
+  if (discovered.length === 0) {
+    throw new Error('No CC-MIRROR instances found. Run `cc-skills instances` to verify discovery.');
+  }
+
+  const selected = selectInstances(discovered, options);
+  if (selected.length === 0) {
+    throw new Error('No target instances selected.');
+  }
+
+  const normalizedSkillsArgs = normalizeSkillsAddArgs(options.skillsArgs);
+  const listOnly = hasListFlag(normalizedSkillsArgs);
+  const targets = listOnly && selected.length > 1 ? selected.slice(0, 1) : selected;
+  const npxArgs = buildSkillsAddNpxArgs(options.source, normalizedSkillsArgs);
+
+  if (listOnly && selected.length > 1) {
+    console.error('`skills add --list` does not depend on the target instance. Running it once for the first selected instance.');
+  }
+
+  const results = [];
+
+  for (const target of targets) {
+    const envPatch = { CLAUDE_CONFIG_DIR: target.configDir };
+    const env = { ...process.env, ...envPatch };
+
+    console.error(`\n==> [${target.name}] ${target.configDir}`);
+
+    if (options.dryRun) {
+      console.log(formatCommand(NPX_BIN, npxArgs, envPatch));
+      results.push({
+        instance: target.name,
+        configDir: target.configDir,
+        ok: true,
+        dryRun: true,
+        exitCode: 0,
+      });
+      continue;
+    }
+
+    const result = runCommand(NPX_BIN, npxArgs, {
+      env,
+      stdio: 'inherit',
+      verbose: options.verbose,
+    });
+
+    const ok = result.status === 0;
+    results.push({
+      instance: target.name,
+      configDir: target.configDir,
+      ok,
+      dryRun: false,
+      exitCode: result.status ?? 1,
+    });
+
+    if (!ok && options.failFast) {
+      break;
+    }
+  }
+
+  const summary = summarizeResults(results);
+  console.error(`\nSummary: ${summary.successCount}/${summary.total} succeeded.`);
+  for (const result of results) {
+    if (result.ok) {
+      console.error(`  ✓ ${result.instance} -> ${result.configDir}`);
+    } else {
+      console.error(`  ✗ ${result.instance} -> ${result.configDir} (exit ${result.exitCode})`);
+    }
+  }
+
+  return summary.failureCount === 0 ? 0 : 1;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    const subcommand = rest[0];
+    if (subcommand === 'add') {
+      printAddHelp();
+      return 0;
+    }
+    if (subcommand === 'instances') {
+      printInstancesHelp();
+      return 0;
+    }
+    printMainHelp();
+    return 0;
+  }
+
+  if (command === '--version' || command === '-v' || command === 'version') {
+    console.log(pkg.version);
+    return 0;
+  }
+
+  switch (command) {
+    case 'instances':
+      return handleInstances(rest);
+    case 'add':
+      return handleAdd(rest);
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}
+
+module.exports = {
+  main,
+};

package/src/lib.js

@@ -0,0 +1,472 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const NPX_BIN = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+const DEFAULT_CC_MIRROR_ROOT = path.join(os.homedir(), '.cc-mirror');
+
+function expandHome(input) {
+  if (!input) return input;
+  if (input === '~') return os.homedir();
+  if (input.startsWith('~/') || input.startsWith('~\\')) {
+    return path.join(os.homedir(), input.slice(2));
+  }
+  return input;
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function formatCommand(command, args, envPatch) {
+  const envPrefix = envPatch
+    ? Object.entries(envPatch)
+        .map(([key, value]) => `${key}=${JSON.stringify(String(value))}`)
+        .join(' ')
+    : '';
+  return [envPrefix, command, ...args].filter(Boolean).join(' ');
+}
+
+function runCommand(command, args, options = {}) {
+  const {
+    env,
+    cwd,
+    stdio = 'pipe',
+    verbose = false,
+  } = options;
+
+  if (verbose) {
+    console.error(`$ ${formatCommand(command, args)}`);
+  }
+
+  const result = spawnSync(command, args, {
+    env,
+    cwd,
+    stdio,
+    encoding: 'utf8',
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  return result;
+}
+
+function parseLooseJsonArray(stdout) {
+  const text = String(stdout || '').trim();
+  if (!text) return [];
+
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const firstBracket = text.indexOf('[');
+    const lastBracket = text.lastIndexOf(']');
+
+    if (firstBracket !== -1 && lastBracket !== -1 && lastBracket > firstBracket) {
+      return JSON.parse(text.slice(firstBracket, lastBracket + 1));
+    }
+
+    throw error;
+  }
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeDiscoveredInstances(instances, ccRoot) {
+  const root = expandHome(ccRoot || DEFAULT_CC_MIRROR_ROOT);
+  const seen = new Set();
+  const result = [];
+
+  for (const instance of Array.isArray(instances) ? instances : []) {
+    if (!instance || typeof instance !== 'object') continue;
+    const name = typeof instance.name === 'string' ? instance.name.trim() : '';
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+
+    const derivedConfigDir = path.join(root, name, 'config');
+    result.push({
+      name,
+      provider: instance.provider ?? null,
+      claudeVersion: instance.claudeVersion ?? null,
+      wrapperPath: instance.wrapperPath ?? null,
+      configDir: instance.configDir ? expandHome(instance.configDir) : derivedConfigDir,
+      raw: instance,
+    });
+  }
+
+  return result;
+}
+
+function discoverInstancesFromFilesystem(ccRoot) {
+  const root = expandHome(ccRoot || DEFAULT_CC_MIRROR_ROOT);
+  if (!fs.existsSync(root)) return [];
+
+  const entries = fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => entry.name !== 'bin' && !entry.name.startsWith('.'));
+
+  const instances = [];
+
+  for (const entry of entries) {
+    const variantDir = path.join(root, entry.name);
+    const variantJsonPath = path.join(variantDir, 'variant.json');
+    const configDir = path.join(variantDir, 'config');
+    const meta = readJsonIfExists(variantJsonPath);
+
+    if (!meta && !fs.existsSync(configDir)) {
+      continue;
+    }
+
+    instances.push({
+      name: entry.name,
+      provider: meta?.provider ?? null,
+      claudeVersion: meta?.nativeVersion ?? null,
+      wrapperPath: meta?.wrapperPath ?? null,
+      configDir: meta?.configDir ? expandHome(meta.configDir) : configDir,
+      raw: meta,
+    });
+  }
+
+  return sanitizeDiscoveredInstances(instances, root);
+}
+
+function discoverInstances(options = {}) {
+  const { ccRoot, ccBinDir, verbose = false } = options;
+  const resolvedRoot = expandHome(ccRoot || DEFAULT_CC_MIRROR_ROOT);
+  const resolvedBinDir = ccBinDir ? expandHome(ccBinDir) : undefined;
+
+  let lastError = null;
+
+  try {
+    const args = ['-y', 'cc-mirror', 'list', '--json'];
+    if (ccRoot) args.push('--root', resolvedRoot);
+    if (resolvedBinDir) args.push('--bin-dir', resolvedBinDir);
+
+    const result = runCommand(NPX_BIN, args, {
+      stdio: 'pipe',
+      verbose,
+    });
+
+    if (result.status === 0) {
+      const parsed = parseLooseJsonArray(result.stdout);
+      return sanitizeDiscoveredInstances(parsed, resolvedRoot);
+    }
+
+    lastError = new Error(result.stderr || result.stdout || `cc-mirror exited with code ${result.status}`);
+  } catch (error) {
+    lastError = error;
+  }
+
+  const fallback = discoverInstancesFromFilesystem(resolvedRoot);
+  if (fallback.length > 0) {
+    if (verbose) {
+      console.error('Falling back to filesystem discovery from CC-MIRROR root.');
+    }
+    return fallback;
+  }
+
+  if (lastError) {
+    throw new Error(
+      `Unable to discover CC-MIRROR instances via \`npx cc-mirror list --json\`: ${lastError.message}`
+    );
+  }
+
+  return [];
+}
+
+function selectInstances(discoveredInstances, options) {
+  const discovered = Array.isArray(discoveredInstances) ? discoveredInstances : [];
+  if (options.allInstances) return discovered;
+
+  const wanted = unique(options.instances || []);
+  const byName = new Map(discovered.map((instance) => [instance.name, instance]));
+  const selected = [];
+  const missing = [];
+
+  for (const name of wanted) {
+    const instance = byName.get(name);
+    if (instance) {
+      selected.push(instance);
+    } else {
+      missing.push(name);
+    }
+  }
+
+  if (missing.length > 0) {
+    const available = discovered.map((instance) => instance.name).sort();
+    const availableText = available.length > 0 ? available.join(', ') : '(none found)';
+    throw new Error(
+      `Unknown CC-MIRROR instance(s): ${missing.join(', ')}. Available instances: ${availableText}`
+    );
+  }
+
+  return selected;
+}
+
+function normalizeSkillsAddArgs(args) {
+  const forwarded = [];
+  let hasGlobal = false;
+  let hasClaudeAgent = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '--all') {
+      throw new Error(
+        'Do not pass `--all` through cc-skills because `skills --all` targets all agents. Use `--skill "*"` instead.'
+      );
+    }
+
+    if (arg === '-g' || arg === '--global') {
+      hasGlobal = true;
+      forwarded.push(arg);
+      continue;
+    }
+
+    if (arg === '--agent') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error('Missing value for `--agent`.');
+      }
+      index += 1;
+      if (value !== 'claude-code') {
+        throw new Error(
+          `cc-skills only targets Claude Code instances. Remove \`--agent ${value}\` or change it to \`--agent claude-code\`.`
+        );
+      }
+      hasClaudeAgent = true;
+      forwarded.push('--agent', value);
+      continue;
+    }
+
+    if (arg.startsWith('--agent=')) {
+      const value = arg.slice('--agent='.length);
+      if (value !== 'claude-code') {
+        throw new Error(
+          `cc-skills only targets Claude Code instances. Remove \`${arg}\` or change it to \`--agent=claude-code\`.`
+        );
+      }
+      hasClaudeAgent = true;
+      forwarded.push(arg);
+      continue;
+    }
+
+    if (arg === '-a') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error('Missing value for `-a`.');
+      }
+      index += 1;
+      if (value !== 'claude-code') {
+        throw new Error(
+          `cc-skills only targets Claude Code instances. Remove \`-a ${value}\` or change it to \`-a claude-code\`.`
+        );
+      }
+      hasClaudeAgent = true;
+      forwarded.push('-a', value);
+      continue;
+    }
+
+    forwarded.push(arg);
+  }
+
+  if (!hasGlobal) {
+    forwarded.unshift('-g');
+  }
+
+  if (!hasClaudeAgent) {
+    forwarded.unshift('claude-code');
+    forwarded.unshift('-a');
+  }
+
+  return forwarded;
+}
+
+function buildSkillsAddNpxArgs(source, normalizedSkillsArgs) {
+  return ['-y', 'skills', 'add', source, ...normalizedSkillsArgs];
+}
+
+function hasListFlag(args) {
+  return args.includes('--list') || args.includes('-l');
+}
+
+function parseInstancesArgs(argv) {
+  const options = {
+    ccRoot: undefined,
+    ccBinDir: undefined,
+    json: false,
+    verbose: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    switch (arg) {
+      case '--cc-root': {
+        const value = argv[index + 1];
+        if (!value) throw new Error('Missing value for `--cc-root`.');
+        options.ccRoot = value;
+        index += 1;
+        break;
+      }
+      case '--cc-bin-dir': {
+        const value = argv[index + 1];
+        if (!value) throw new Error('Missing value for `--cc-bin-dir`.');
+        options.ccBinDir = value;
+        index += 1;
+        break;
+      }
+      case '--json':
+        options.json = true;
+        break;
+      case '--verbose':
+        options.verbose = true;
+        break;
+      case '--help':
+      case '-h':
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown option for \`instances\`: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function parseAddArgs(argv) {
+  const options = {
+    source: undefined,
+    instances: [],
+    allInstances: false,
+    ccRoot: undefined,
+    ccBinDir: undefined,
+    dryRun: false,
+    failFast: false,
+    verbose: false,
+    help: false,
+    skillsArgs: [],
+  };
+
+  let passthroughMode = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (passthroughMode) {
+      options.skillsArgs.push(arg);
+      continue;
+    }
+
+    if (arg === '--') {
+      passthroughMode = true;
+      continue;
+    }
+
+    if (!options.source && !arg.startsWith('-')) {
+      options.source = arg;
+      continue;
+    }
+
+    switch (arg) {
+      case '--instance':
+      case '-i': {
+        const value = argv[index + 1];
+        if (!value) throw new Error(`Missing value for \`${arg}\`.`);
+        options.instances.push(value);
+        index += 1;
+        break;
+      }
+      case '--all-instances':
+        options.allInstances = true;
+        break;
+      case '--cc-root': {
+        const value = argv[index + 1];
+        if (!value) throw new Error('Missing value for `--cc-root`.');
+        options.ccRoot = value;
+        index += 1;
+        break;
+      }
+      case '--cc-bin-dir': {
+        const value = argv[index + 1];
+        if (!value) throw new Error('Missing value for `--cc-bin-dir`.');
+        options.ccBinDir = value;
+        index += 1;
+        break;
+      }
+      case '--dry-run':
+        options.dryRun = true;
+        break;
+      case '--fail-fast':
+        options.failFast = true;
+        break;
+      case '--verbose':
+        options.verbose = true;
+        break;
+      case '--help':
+      case '-h':
+        options.help = true;
+        break;
+      default:
+        options.skillsArgs.push(arg);
+        break;
+    }
+  }
+
+  options.instances = unique(options.instances);
+
+  if (!options.help) {
+    if (!options.source) {
+      throw new Error('Missing required <source> for `cc-skills add`.');
+    }
+    if (options.allInstances && options.instances.length > 0) {
+      throw new Error('Use either `--all-instances` or `--instance`, not both.');
+    }
+    if (!options.allInstances && options.instances.length === 0) {
+      throw new Error('Choose a target with `--instance <name>` or `--all-instances`.');
+    }
+  }
+
+  return options;
+}
+
+function summarizeResults(results) {
+  const successes = results.filter((result) => result.ok);
+  const failures = results.filter((result) => !result.ok);
+  return {
+    total: results.length,
+    successCount: successes.length,
+    failureCount: failures.length,
+    successes,
+    failures,
+  };
+}
+
+module.exports = {
+  DEFAULT_CC_MIRROR_ROOT,
+  NPX_BIN,
+  buildSkillsAddNpxArgs,
+  discoverInstances,
+  discoverInstancesFromFilesystem,
+  expandHome,
+  formatCommand,
+  hasListFlag,
+  normalizeSkillsAddArgs,
+  parseAddArgs,
+  parseInstancesArgs,
+  parseLooseJsonArray,
+  runCommand,
+  selectInstances,
+  summarizeResults,
+  unique,
+};