# sk-cli

AI Agent 技能管理工具 - 创建、上传、安装和分发技能，基于 Git 仓库存储分发技能（支持研发云）。

---

## 快速开始

### 安装

```bash
# 方式一：npm 安装（推荐）
npm install -g @archest/sk-cli

# 方式二：指定版本安装
npm install -g @archest/sk-cli@1.0.0

# 如果 npm 报 403 错误，可能需要配置 token
# 详见下方 "常见问题"
```

### 配置 PATH 环境变量

如果安装后找不到 `sk` 命令，需要将 npm 全局 bin 目录添加到 PATH：

#### Windows (PowerShell)

```powershell
# 查看 npm 全局路径
npm config get prefix

# 假设输出 C:\Users\你的用户名\AppData\Roaming\npm
# 将以下路径添加到 PATH：
# C:\Users\你的用户名\AppData\Roaming\npm

# 临时生效（当前终端有效）
$env:PATH = "$env:PATH;C:\Users\你的用户名\AppData\Roaming\npm"

# 永久生效（系统属性 -> 高级 -> 环境变量 -> 用户变量 -> Path）
```

#### Windows (CMD / Git Bash)

```cmd
REM 查看 npm 全局路径
npm config get prefix

REM 添加到 PATH（假设输出 C:\Users\xxx\AppData\Roaming\npm）
setx PATH "%PATH%;C:\Users\你的用户名\AppData\Roaming\npm"
```

#### macOS / Linux (bash)

```bash
# 查看 npm 全局路径
npm config get prefix

# 添加到 PATH
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

# 或 zsh
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc
source ~/.zshrc
```

验证安装：

```bash
sk --version
```

### 常用指令组合

完整开发流程：

```bash
# 1. 开发技能
sk init my-skill          # 初始化技能
# 编辑 .skills/my-skill/SKILL.md
sk validate               # 验证技能格式

# 2. 发布技能到远程仓库
sk publish git@github.com:your-name/your-skills-repo.git

# 3. 其他人添加市场并安装
sk market add git@github.com:your-name/your-skills-repo.git  # 添加市场
sk search my-skill        # 搜索技能
sk install my-skill       # 安装技能

# 4. 升级技能
sk update                 # 更新所有技能
sk update my-skill        # 更新指定技能
```

指定目录示例：

```bash
# 发布指定目录下的技能
sk publish git@github.com:user/repo.git --dir ./my-skills

# 安装仓库中所有技能到指定目录
sk install git@github.com:user/repo.git --target ~/my-skills

# 从市场安装指定技能到指定目录
sk install skill-name --target ~/my-skills

# 安装指定仓库的指定技能到指定目录
sk install git@github.com:user/repo.git --skill skill-name --target ./custom-dir
```

---

## 指令总结

| 分类 | 命令 | 说明 |
|------|------|------|
| **开发** | `sk init <name>` | 初始化新技能 |
| | `sk validate [path]` | 验证技能格式 |
| **发布** | `sk publish <repo-url>` | 发布技能到远程仓库 |
| **安装** | `sk install <skill\|repo>` | 安装技能 |
| | `sk update [skill-name]` | 更新技能 |
| | `sk uninstall <skill-name>` | 卸载技能 |
| | `sk list` | 列出已安装的技能 |
| **锁定** | `sk pin <skill-name> [version]` | 锁定技能版本 |
| **市场** | `sk market add <source>` | 添加市场 |
| | `sk market list` | 列出市场 |
| | `sk market enable <name>` | 启用市场 |
| | `sk market disable <name>` | 禁用市场 |
| | `sk market remove <name>` | 移除市场 |
| **搜索** | `sk search [query]` | 搜索技能 |
| **配置** | `sk config list` | 查看配置 |
| | `sk config get <key>` | 获取配置值 |
| | `sk config set <key> <value>` | 设置配置值 |
| | `sk config reset` | 重置配置 |
| **诊断** | `sk doctor` | 诊断系统状态 |

---

## 指令详解

### 技能开发

#### `sk init <name>`

在当前目录初始化一个新技能。

```bash
# 在当前目录创建技能
sk init code-reviewer

# 在指定目录创建技能
sk init code-reviewer --dir /path/to/dir
```

#### `sk validate [path]`

验证技能格式是否正确。

```bash
# 验证本地技能
sk validate ./my-skill

# 验证远程仓库中的技能
sk validate https://github.com/user/repo.git --skill skill-name
```

### 技能发布

#### `sk publish <repo-url>`

发布技能到远程仓库，自动更新 marketplace.json。

```bash
# 使用默认配置目录
sk publish git@github.com:user/my-skills.git

# 指定自定义目录
sk publish git@github.com:user/my-skills.git --dir .my-skills

# 指定技能来源仓库和分支
sk publish git@github.com:user/my-skills.git --source https://github.com/user/other-repo.git --ref v1.0.0

# 指定远程仓库中 marketplace.json 所在目录
sk publish git@github.com:user/my-skills.git --marketplace-dir .claude-plugin
```

### 技能安装

#### `sk install [<skill-name>|<repo-url>]`

从远程仓库或已配置的市场安装技能。

```bash
# 从已配置的市场安装技能（自动搜索所有市场）
sk install helloworld

# 使用 skill@marketplace 格式从指定市场安装
sk install document-skills@anthropic-agent-skills

# 从远程仓库安装所有技能
sk install git@github.com:user/skills-repo.git

# 从远程仓库安装指定技能
sk install git@github.com:user/skills-repo.git --skill my-skill

# 安装特定版本
sk install git@github.com:user/skills-repo.git --version v1.0.0

# 安装到指定目录
sk install git@github.com:user/skills-repo.git --target ~/my-skills
```

**参数说明：**
- 第一个参数可以是技能名称、skill@marketplace 格式或仓库地址
- 如果参数包含 `://` 或以 `git@` 开头，则视为仓库地址
- 如果包含 `@`（如 `skill@marketplace`），从指定市场安装
- 否则视为技能名称，从所有已配置的 marketplaces 中搜索安装
- 支持的 marketplace 格式：`.skills-market/`, `.claude-plugin/`, 根目录
- 支持的 source 格式：字符串(`"./"`)、对象(`{url/ref}`)、Anthropic(`{github:{repo/ref}}`)

#### `sk update [skill-name]`

检查并更新已安装的技能到最新版本。如果没有可用更新，则跳过该技能。

```bash
# 更新所有技能（有更新才更新，没更新跳过）
sk update

# 更新指定技能
sk update my-skill

# 强制更新（忽略锁定）
sk update --force
```

#### `sk uninstall <skill-name>`

卸载技能。

```bash
sk uninstall my-skill
```

#### `sk list`

列出已安装的技能。

```bash
sk list
```

### 技能管理

#### `sk pin <skill-name> [version]`

锁定技能版本。

```bash
# 锁定到当前版本
sk pin my-skill

# 锁定到指定版本
sk pin my-skill v1.0.0

# 解除锁定
sk pin my-skill --unpin
```

### 市场管理

#### `sk market add <source>`

添加技能市场。支持两种 marketplace 目录格式：
- `.skills-market/marketplace.json` (sk 格式)
- `.claude-plugin/marketplace.json` (Anthropic Claude 格式)

```bash
# 添加自定义市场
sk market add git@github.com:user/marketplace.git

# 添加 Anthropic 官方技能市场
sk market add https://github.com/anthropics/skills
```

#### `sk market list`

列出已添加的市场。

```bash
sk market list
```

#### `sk market enable <name>`

启用市场。

```bash
sk market enable marketplace-name
```

#### `sk market disable <name>`

禁用市场。禁用后搜索和安装将跳过该市场。

```bash
sk market disable marketplace-name
```

#### `sk market remove <name>`

移除市场。

```bash
sk market remove marketplace-name
```

### 搜索

#### `sk search [query]`

在市场中搜索技能。

```bash
# 搜索技能
sk search "代码生成"

# 按标签搜索
sk search --tag 开发

# 在指定市场搜索
sk search --marketplace my-market
```

### 配置管理

#### `sk config list`

查看所有配置。

```bash
sk config list
```

#### `sk config get <key>`

获取配置值。

```bash
sk config get skills.downloadSkillDir
sk config get network.timeout
```

#### `sk config set <key> <value>`

设置配置值。

```bash
sk config set skills.downloadSkillDir "/path/to/skills"
sk config set network.timeout 60
sk config set autoUpdate.enabled false
```

#### `sk config reset`

重置为默认配置。

```bash
sk config reset
```

### 诊断

#### `sk doctor`

诊断技能系统状态。

```bash
sk doctor
```

---

## 常见问题

### Q: Windows 安装后找不到 sk 命令？

Windows 上 npm 全局包默认安装到 `%AppData%\npm`，需要确保该路径在 PATH 中：

```powershell
# PowerShell 中查看
npm config get prefix
# 输出类似：C:\Users\你的用户名\AppData\Roaming\npm

# 临时添加（当前终端有效）
$env:PATH += ";$env:APPDATA\npm"

# 验证
sk --version
```

详见上方 "配置 PATH 环境变量" 部分。

### Q: npm publish 报 403 错误？

需要生成具有 publish 权限的 NPM Access Token：

1. 登录 https://www.npmjs.com/settings/-/tokens
2. 创建 "Granular Access Token"，勾选 Publish 权限
3. 在本地配置 token：
   ```bash
   echo "//registry.npmjs.org/:_authToken=YOUR_TOKEN" >> ~/.npmrc
   ```
4. 或使用 npmmirror 时：
   ```bash
   npm config set //registry.npmmirror.com/:_authToken YOUR_TOKEN
   ```

### Q: 如何修改技能安装目录？

```bash
sk config set skills.downloadSkillDir "~/my-custom-path"
```

### Q: 如何使用内部 Git 仓库？

```bash
sk install git@git.internal.com:user/repo.git
```

### Q: 如何查看已安装的技能？

```bash
sk list
```

### Q: 如何更新所有技能？

```bash
sk update
```
