npm package: @sstar/skill_manager
Description: CLI for discovering, browsing, installing, and uninstalling skills from local or remote Git repositories.
Latest version: 1.0.2

# @sstar/skill_manager

`@sstar/skill_manager` 是一个命令行工具，用于从本地或远程 Git 仓库发现、浏览、安装和卸载技能。

## 功能概述

- **多源支持**：支持本地目录、HTTP/HTTPS URL、SSH Git 地址作为技能仓库源
- **技能发现**：自动扫描仓库中的 `SKILL.md` 文件，提取技能元信息
- **交互式安装**：提供终端 UI，���用户通过多选界面选择要安装的技能
- **交互式卸载**：可浏览本地已安装技能列表并按需选择卸载
- **搜索过滤**：支持按名称、描述或路径搜索技能
- **CI/CD 优化**：支持 `--non-interactive` 模式，延迟加载交互库，加快启动速度
- **JSON 输出**：支持 JSON 格式输出，便于脚本集成

## 安装

```bash
# 全局安装（推荐）
npm install -g @sstar/skill_manager

# 或使用 npx（每次运行会下载依赖，较慢）
npx @sstar/skill_manager list
```

### 开发态验证

如果你就在这个仓库源码目录里验证 CLI，不要用 `npx @sstar/skill_manager`。
在包源码根目录中，npm 会优先把当前目录当作本地项目处理，而不是重新从 npmjs 下载已发布版本。

可用的本地验证方式：

```bash
# 在源码目录内直接执行本地包
npx . --help

# 或执行编译后的入口
node dist/cli.js --help
```

如果要验证 npmjs 上已发布的版本，请切到一个干净目录后再执行：

```bash
mkdir -p /tmp/skill-manager-smoke
cd /tmp/skill-manager-smoke
npx @sstar/skill_manager --help
```

## 使用

### 列出技能

```bash
# 列出默认仓库中的所有技能
skill_manager list

# 列出本地仓库中的所有技能
skill_manager list /path/to/skills-repo

# 列出远程仓库中的所有技能
skill_manager list https://github.com/example/skills.git

# 搜索包含 "git" 关键字的技能
skill_manager list --query git

# 以 JSON 格式输出（便于脚本处理）
skill_manager list --json

# CI/CD 模式（禁用交互提示）
skill_manager list --json --non-interactive
```

### 安装技能

```bash
# 交互式选择并安装（进入 TUI 界面）
skill_manager install

# 安装到项目目录
skill_manager install repo-git --scope project

# 安装到全局目录
skill_manager install repo-git --scope global

# 安装多个技能
skill_manager install repo-git brainstorming --scope project

# 从指定源安装
skill_manager install /path/to/skills-repo repo-git --scope project

# CI/CD 模式（必须指定技能和作用域）
skill_manager install repo-git --scope project --non-interactive
```

### 卸载技能

```bash
# 交互式选择并卸载
skill_manager uninstall

# 卸载指定技能（交互式确认）
skill_manager uninstall repo-git

# 卸载指定作用域的技能
skill_manager uninstall global:repo-git
skill_manager uninstall project:repo-git

# 跳过确认直接卸载
skill_manager uninstall repo-git --yes

# CI/CD 模式
skill_manager uninstall global:repo-git --yes --non-interactive
```

## 命令参考

### `skill_manager list [source] [options]`

列出技能仓库中的所有技能。

| 参数 | 说明 |
|------|------|
| `[source]` | 技能仓库路径（本地目录、HTTP/HTTPS URL 或 SSH Git 地址），省略时使用内置默认仓库 |
| `-q, --query <text>` | 按名称、描述或路径过滤技能 |
| `--json` | 以 JSON 格式输出 |
| `--non-interactive` | CI/CD 模式：禁用交互提示 |

### `skill_manager install [args...] [options]`

从技能仓库安装技能到目标目录。

| 参数 | 说明 |
|------|------|
| `[args...]` | 支持 `<source> <skill...>` 或直接 `<skill...>`，省略 source 时使用内置默认仓库 |
| `-s, --scope <scope>` | 安装作用域：`project` 或 `global` |
| `-q, --query <text>` | 交互模式下预过滤技能 |
| `-f, --force` | 强制覆盖已存在内容 |
| `--non-interactive` | CI/CD 模式：缺少 skill 或 scope 时直接报错 |

### `skill_manager uninstall [skills...] [options]`

浏览并卸载目标目录中的已安装技能。

| 参数 | 说明 |
|------|------|
| `[skills...]` | 要卸载的技能名称，支持 `global:xxx` / `project:xxx` 格式，省略时进入交互式选择 |
| `-y, --yes` | 跳过确认直接卸载 |
| `--non-interactive` | CI/CD 模式：缺少 skill 时直接报错 |

### 作用域与目标目录

| Scope | 安装目录 | Claude 兼容链接 |
|-------|----------|----------------|
| `project` | `./.agents/skills` | `./.claude/skills` |
| `global` | `~/.agents/skills` | `~/.claude/skills` |

## 使用场景示例

### 场景一：快速浏览可用技能

```bash
skill_manager list
```

输出示例：
```
◆ Skill Manager - List Skills
│
│ [1/19] code-reviewer-lookup [common] v1.0.0
│     查询代码仓库的 Code Review +2 权限人员
│     skills/common/code-reviewer-lookup
│
│ [2/19] repo-git [common] v1.0.0
│     提供 repo 多仓 Git 的强约束全流程
│     skills/common/repo-git
...
```

### 场景二：搜索特定功能的技能

```bash
skill_manager list --query git
```

### 场景三：交互式安装

```bash
# 启动交互界面，选择需要的技能
skill_manager install --scope project
```

### 场景四：CI/CD 中预安装技能

```bash
# 在 CI 环境中自动安装指定技能，无需交互
skill_manager install repo-git brainstorming --scope project --non-interactive
```

### 场景五：卸载技能

```bash
# 交互式选择卸载
skill_manager uninstall

# 直接卸载指定技能
skill_manager uninstall global:repo-git --yes
```

## 架构说明

```
skill_manager/
├── src/
│   ├── cli.ts           # CLI 入口，解析命令行参数
│   ├── index.ts         # 公共 API 导出
│   ├── repository.ts    # 仓库源解析（本地路径 / 远程 Git）
│   ├── catalog.ts       # 技能目录构建与过滤
│   ├── install.ts       # 技能安装逻辑
│   ├── uninstall.ts     # 已安装技能扫描与卸载逻辑
│   ├── targets.ts       # 目标目录解析
│   ├── types.ts         # 类型定义
│   ├── install-cli-args.ts  # 安装命令参数解析
│   └── ui/
│       ├── index.ts     # 轻量级 UI 工具（spinner, colors 等）
│       ├── prompts.ts   # 交互式 UI（延迟加载）
│       └── ink/         # Ink TUI 组件
├── tests/               # 测试文件
├── package.json
└── tsconfig.json
```

### 核心流程

1. **仓库解析** (`repository.ts`)：判断输入源是本地路径还是远程 Git 地址，远程时自动克隆到临时目录
2. **目录构建** (`catalog.ts`)：递归扫描仓库，解析所有 `SKILL.md` 文件的 YAML frontmatter，构建技能目录
3. **技能过滤** (`catalog.ts`)：根据 `--query` 参数过滤技能列表
4. **交互选择** (`ui/prompts.ts`)：未指定技能名称或作用域时，启动交互式选择界面
5. **安装执行** (`install.ts`)：将选中的技能目录复制到目标位置，并创建 Claude 兼容软链接
6. **卸载执行** (`uninstall.ts`)：扫描目标位置下的已安装技能并删除选中目录

### 性能优化

- **延迟加载**：交互式 UI 组件（ink, react）仅在需要时加载
- **CI/CD 模式**：`--non-interactive` 模式下不加载任何交互库，启动更快

### 技能作用域

技能根据目录位置自动识别作用域：

| 目录前缀 | 作用域 |
|----------|--------|
| `skills/common/` | `common` - 通用技能 |
| `skills/third_party/` | `third_party` - 第三方技能 |
| 其他 | `site` - 站点特定技能 |

## 开发指南

### 环境准备

```bash
# 克隆仓库
git clone <repository-url>
cd skill_manager

# 安装依赖
npm install
```

### 构建

```bash
npm run build
```

编译产物输出到 `dist/` 目录。

### 测试

```bash
npm run test
```

使用 Vitest 作为测试框架。

### 本地调试

```bash
# 构建后直接运行
node dist/cli.js list

# 或链接到全局
npm link
skill_manager list
```

### 发布

```bash
# 更新版本号
npm version patch|minor|major

# 发布到 npm
npm publish
```

## 许可证

MIT