npm package: @sstar/skill-install
Description: Agent Skill installation tool - download, extract, validate, and install skills for Claude Code and Codex
Author: ekko.bao
Latest version: 1.2.3

# Agent Skill 安装工具

命令行工具，用于从多种来源（公开 URL、需要认证的 Wiki 或本地归档文件）安装 Agent Skills。自动下载、解压、验证并安装技能到 **Claude Code** 或 **Codex**。

## 功能特性

- **多工具支持**：同时支持 Claude Code (`~/.claude/skills/`) 和 Codex (`~/.agents/skills/`)
- **自动检测来源**：自动识别来源类型（公开 URL、需认证的 Wiki URL 或本地文件）
- **多种归档格式**：支持 `.zip`、`.skill`、`.tar.gz`、`.tgz`，并优先按文件内容识别
- **严格验证**：验证归档包含有效的 `SKILL.md` 文件及必需的 frontmatter
- **Wiki 认证**：支持内部 Confluence Wiki 的身份认证
- **技能管理**：列出已安装的技能并支持卸载
- **交互式提示**：可选择全局/本地目录和 AI 工具
- **自签名证书**：内置支持企业 SSL 证书

## 什么是 Skills？

Skills 是一种轻量级的开放格式，用于通过专业知识和工作流扩展 AI 代理的能力。本质上，一个 skill 是一个包含 `SKILL.md` 文件的文件夹，该文件包含元数据（`name` 和 `description`）和指令。

了解更多：https://agentskills.io/what-are-skills

## 安装

```bash
cd /home/ekko.bao/work/tools/wiki_download
npm install
npm run build
npm link  # 可选：全局安装
```

## 使用方法

```bash
# 交互式安装（提示选择 AI 工具和目录）
skill-install install https://github.com/user/repo/archive/main.zip

# 指定 AI 工具安装（跳过提示）
skill-install -t claude install https://github.com/user/repo/archive/main.zip
skill-install -t codex install https://github.com/user/repo/archive/main.zip

# 显式安装到全局目录
skill-install install https://example.com/skill.zip --global

# 显式安装到本地目录
skill-install install https://example.com/skill.zip --local

# 安装到自定义目录
skill-install -s /path/to/skills install https://example.com/skill.zip

# 从需要认证的 Wiki 安装
skill-install install https://wiki.company.com/download/attachments/123/skill.zip -u username

# 从本地归档文件安装
skill-install install ./my-skill.zip

# 列出已安装的技能（提示选择 AI 工具）
skill-install list

# 列出指定 AI 工具的技能（跳过提示）
skill-install -t claude list
skill-install -t codex list

# 列出全局和本地目录的所有技能
skill-install list --all

# 卸载技能（提示选择 AI 工具）
skill-install uninstall my-skill

# 从指定 AI 工具卸载（跳过提示）
skill-install -t claude uninstall my-skill
skill-install -t codex uninstall my-skill

# 技能已存在时强制重新安装
skill-install install ./my-skill.zip --force
```

## 命令选项

### 全局选项
| 选项 | 描述 |
|------|------|
| `-t, --tool <tool>` | AI 工具：`claude` 或 `codex`（指定后跳过提示） |
| `-s, --skills-dir <path>` | 自定义技能目录 |
| `-v, --verbose` | 启用详细日志 |
| `-h, --help` | 显示帮助信息 |

**注意**：如果未指定 `-t`，工具将提示交互选择 Claude Code 或 Codex。

### install 命令
| 选项 | 描述 |
|------|------|
| `<source>` | 技能归档的 URL 或本地文件路径 |
| `-g, --global` | 安装到全局目录 (`~/.claude/skills/` 或 `~/.agents/skills/`) |
| `-l, --local` | 安装到本地目录 (`./.claude/skills/` 或 `./.agents/skills/`) |
| `-u, --username <username>` | Wiki 用户名（用于 Wiki URL） |
| `-p, --password <password>` | Wiki 密码（或使用环境变量） |
| `--allow-self-signed` | 允许自签名 SSL 证书（默认：true） |
| `-f, --force` | 技能已存在时重新安装 |

**注意**：如果未指定 `-g`、`-l` 或 `-s`，工具将提示交互选择全局或本地目录。

### list 命令
| 选项 | 描述 |
|------|------|
| `-a, --all` | 列出全局和本地目录的所有技能 |

### uninstall 命令
| 选项 | 描述 |
|------|------|
| `[name]` | 要卸载的技能名称（可选 - 留空可从列表中选择） |
| `-y, --yes` | 跳过确认提示 |

**注意**：如果未提供技能名称，工具将显示所有已安装的技能并允许通过输入数字来选择要卸载的技能（例如 `1 3 5`）。

## 环境变量

| 变量 | 描述 |
|------|------|
| `WIKI_USERNAME` | 默认 Wiki 用户名 |
| `WIKI_PASSWORD` | 默认 Wiki 密码 |

## 技能验证

有效的技能必须在根目录包含 `SKILL.md` 文件，其中包含 YAML frontmatter：

```yaml
---
name: my-skill
description: 对该技能功能的简要描述
---

# My Skill

给代理的指令...
```

工具会验证：
- `SKILL.md` 文件存在
- YAML frontmatter 存在（用 `---` 包裹）
- `name` 字段存在
- `description` 字段存在

## 技能目录结构

根据 AI 工具的不同，技能可以安装到不同位置：

### Claude Code
- **全局**：`~/.claude/skills/` - 所有项目可用
- **本地**：`./.claude/skills/` - 项目特定

### Codex
- **全局**：`~/.agents/skills/` - 所有项目可用
- **本地**：`./.agents/skills/` - 项目特定
- **兼容**：读取与卸载时会兼容旧目录 `~/.codex/skills/` 和 `./.codex/skills/`

### 目录选择
- **全局**：使用 `--global` 标志或提示时选择 "1"（推荐用于常用技能）
- **本地**：使用 `--local` 标志或提示时选择 "2"（推荐用于项目特定技能）
- **自定义**：使用 `-s /path/to/skills` 指定自定义位置

典型的已安装技能结构：

```
~/.claude/skills/my-skill/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档
└── assets/           # 可选：模板、资源
```

## 使用示例

### 交互式安装（提示选择 AI 工具和目录）

```bash
skill-install install https://github.com/user/repo/archive/main.zip

# 输出：
# Select AI tool:
#   1. Claude Code (~/.claude/skills/)
#   2. Codex      (~/.agents/skills/)
#
# Choose [1/2]: 1
#
# Select installation directory:
#   1. Global: /home/user/.claude/skills
#   2. Local:  /home/user/project/.claude/skills
#
# Choose [1/2]: 1
```

### 为指定 AI 工具安装（跳过提示）

```bash
# 为 Claude Code 安装
skill-install -t claude install https://example.com/skill.zip

# 为 Codex 安装
skill-install -t codex install https://example.com/skill.zip

# 安装到 Codex 全局目录
skill-install -t codex install https://example.com/skill.zip --global
```

### 安装到指定目录

```bash
# 安装到全局目录
skill-install install https://example.com/skill.zip --global

# 安装到本地目录
skill-install install https://example.com/skill.zip --local

# 安装到自定义目录
skill-install -s /custom/path install https://example.com/skill.zip
```

### 从 Wiki 安装

```bash
skill-install install "https://wiki.company.com/download/attachments/12345/skill.zip?api=v2" -u john.doe
```

### 从本地文件安装

```bash
skill-install install ~/Downloads/my-skill.tar.gz
```

### 列出和卸载

```bash
# 列出技能（提示选择 AI 工具）
skill-install list

# 列出指定 AI 工具的技能（跳过提示）
skill-install -t claude list
skill-install -t codex list

# 列出两个目录的所有技能
skill-install -t claude list --all

# 卸载指定技能（提示选择 AI 工具）
skill-install uninstall my-skill

# 无提示卸载（指定 AI 工具并跳过确认）
skill-install -t codex uninstall my-skill -y

# 交互式卸载（从列表选择）
skill-install uninstall

# 输出：
# Select AI tool:
#   1. Claude Code (~/.claude/skills/)
#   2. Codex      (~/.agents/skills/)
#
# Choose [1/2]: 1
#
# Installed skills:
#
#   [1] repo-git
#       Provides multi-repository version control capabilities.
#
#   [2] pdf-processing
#       Extract text and tables from PDF files.
#
# Enter the numbers of the skills to uninstall (separated by spaces, e.g., "1 3 5"):
# Press Enter to cancel:
# Your choice: 1 2
#
# Selected skills: repo-git, pdf-processing
```

## 项目结构

```
src/
├── cli.ts                    # CLI 入口
├── installer/
│   └── install-service.ts    # 核心安装逻辑
├── download/
│   └── download-manager.ts   # 下载管理器（wiki + 公共）
├── archive/
│   └── archive-extractor.ts  # 归档解压（ZIP、tar.gz）
├── source/
│   └── source-detector.ts    # 来源类型检测
├── skills/
│   ├── skills-manager.ts     # 列表/卸载操作
│   └── skill-validator.ts    # SKILL.md 验证
├── auth/                     # Wiki 认证
├── http/                     # 带 Cookie 的 HTTP 客户端
└── core/                     # 错误处理和日志
```

## 许可证

MIT