npm package: @jianghuizhong/uskill
Description: uskill.cn CLI — search, install, and publish agent skills (token-only auth)
Latest version: 1.0.2

# @jianghuizhong/uskill

uskill.cn 官方 CLI 工具，用于搜索、安装、发布 Agent 技能。基于 ClawHub 协议，默认使用 uskill.cn 作为技能注册表，采用 Token 登录（无需浏览器 OAuth）。

**当前版本**：1.0.2

---

## 一、安装

### 1.1 全局安装（推荐）

```bash
npm install -g @jianghuizhong/uskill
```

或使用 pnpm：

```bash
pnpm add -g @jianghuizhong/uskill
```

不指定版本时，将自动安装最新版。

### 1.2 验证安装

```bash
uskill --help
```

若能看到 ClawHub 命令列表，说明安装成功。

### 1.3 更新到最新版

已安装用户可执行：

```bash
npm update -g @jianghuizhong/uskill
```

---

## 二、登录（Token）

发布技能前需先登录。uskill 采用 **Token 登录**，无需浏览器。

### 2.1 获取 Token

从 [uskill.cn](https://uskill.cn) 获取发布 Token：

- 联系管理员获取
- 或在 uskill.cn 的开发者/CLI 页面查看获取方式

### 2.2 执行登录

```bash
uskill login --token <你的Token>
```

示例：

```bash
uskill login --token clh_xxxxxxxxxxxxxxxx
```

登录成功后会显示：`OK. Logged in. Token saved.`

### 2.3 Token 存储位置

| 系统 | 路径 |
|------|------|
| Linux / macOS | `~/.config/uskill/config.json` |
| Windows | `%APPDATA%\uskill\config.json` |

### 2.4 登出

```bash
uskill logout
```

---

## 三、常用命令

### 3.1 搜索技能

```bash
uskill search <关键词>
```

示例：

```bash
uskill search cursor
uskill search 文档
```

### 3.2 安装技能

```bash
uskill install <slug> [选项]
```

示例：

```bash
# 安装最新版
uskill install my-skill

# 安装指定版本
uskill install my-skill --version 1.2.0

# 强制覆盖已存在的目录
uskill install my-skill --force
```

技能会安装到当前目录下的 `skills/<slug>`。

### 3.3 查看已安装技能

```bash
uskill list
```

### 3.4 更新技能

```bash
# 更新指定技能
uskill update my-skill

# 更新所有已安装技能
uskill update --all
```

### 3.5 卸载技能

```bash
uskill uninstall <slug>
```

### 3.6 浏览技能

```bash
uskill explore [选项]
```

示例：

```bash
uskill explore --limit 20
uskill explore --sort newest
```

### 3.7 查看技能详情（不安装）

```bash
uskill inspect <slug>
```

---

## 四、发布技能

### 4.1 前置条件

- 已执行 `uskill login --token <token>`
- 本地有符合规范的技能目录（含 `SKILL.md`）

### 4.2 发布命令

```bash
uskill publish <技能目录路径> [选项]
```

常用选项：

| 选项 | 说明 |
|------|------|
| `--slug <slug>` | 技能标识（必填） |
| `--name <name>` | 显示名称 |
| `--version <version>` | 版本号（semver） |
| `--changelog <text>` | 更新说明 |
| `--tags <tags>` | 标签，逗号分隔 |

### 4.3 发布示例

```bash
# 基本发布
uskill publish ./my-skill --slug my-skill --version 1.0.0

# 完整参数
uskill publish ./my-skill \
  --slug my-skill \
  --name "我的技能" \
  --version 1.0.0 \
  --changelog "首次发布"
```

### 4.4 技能目录结构

```
my-skill/
├── SKILL.md          # 必需，技能主文档
├── scripts/          # 可选，脚本
├── references/       # 可选，参考文件
└── assets/           # 可选，资源文件
```

---

## 五、环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `USKILL_CONFIG_PATH` | 配置文件路径 | 见上文「Token 存储位置」 |
| `CLAWHUB_SITE` | 站点地址 | `https://uskill.cn` |
| `CLAWHUB_REGISTRY` | 注册表 API 地址 | `https://uskill.cn` |
| `CLAWHUB_WORKDIR` | 工作目录 | 当前目录 |
| `CLAWHUB_PUBLISH_TOKEN` | 发布 Token（可替代 login） | 从 config 读取 |

---

## 六、CI / 自动化

在 CI 中可使用环境变量传入 Token，无需 `uskill login`：

```bash
export CLAWHUB_PUBLISH_TOKEN="你的Token"
uskill publish ./my-skill --slug my-skill --version 1.0.0 --no-input
```

或一行执行：

```bash
CLAWHUB_PUBLISH_TOKEN="你的Token" uskill publish ./my-skill --slug my-skill --version 1.0.0 --no-input
```

---

## 七、故障排查

### 7.1 登录失败

- 确认 Token 正确，可从 uskill.cn 重新获取
- 检查网络，确保能访问 `https://uskill.cn`

### 7.2 发布 403

- 确认已登录：`uskill login --token <token>`
- 或设置 `CLAWHUB_PUBLISH_TOKEN` 环境变量

### 7.3 命令未找到

- 确认全局安装成功：`npm list -g @jianghuizhong/uskill`
- 检查 PATH 是否包含 npm 全局 bin 目录

### 7.4 首次运行较慢

若未安装 clawhub，uskill 会通过 npx 自动调用，首次可能需下载依赖，稍等即可。

---

## 八、相关链接

- **uskill.cn**：https://uskill.cn
- **CLI 说明页**：https://uskill.cn/zh-CN/cli
- **npm 包**：https://www.npmjs.com/package/@jianghuizhong/uskill
- **GitHub**：https://github.com/18701745572/uskill.cn

---

## 与 clawhub 的关系

uskill 基于 [clawhub](https://www.npmjs.com/package/clawhub)，默认使用 uskill.cn 作为 registry，并采用 Token 登录（无浏览器 OAuth）。若未安装 clawhub，将自动通过 npx 调用。