CLI 使用参考

SkillHub CLI 是 SkillHub 的第一方命令行工具，用于搜索、安装、管理和发布 Agent 技能包。

选择正确的管理对象

目标	命令	影响范围
安装单个远端 Skill	install	选定 Agent / scope / 自定义目录
更新已安装单个技能	upgrade	显式选择的坐标及目标，不隐式升级全部
管理固定版本集合	suite	套装安装记录及成员来源
同步团队创作工作区	sync	非 global 空间与工作区，不等于套装管理
更新 CLI 程序本身	update	本机 CLI 安装，不更新技能
修复本地记录	doctor	扫描项目元数据并重建 inventory，不代替远端升级

自动化和错误处理

自动化安装明确给出 --scope 与 --agent，或单独使用 --dir，避免依赖工作目录中的自动发现结果。--dir 不与 scope/agent 混用。先使用 version 和 help <command> 核对本机命令；文档对应当前代码，不保证老版本全部支持。

同一工作流的搜索、登录、安装和检查应指向同一 Registry。显式 --registry 适合单次操作；环境变量适合当前进程树。凭证按 Registry 保存，切换地址后使用 whoami 核对身份。

--json 用于机器读取，不要在自动化中假设会出现交互提示。捕获退出码和输出；遇到结构化服务端错误保留公开消息与 requestId。Suite 检查的 ok: false 可以只是发现变化，需继续读取结果字段。--check 是相应升级/同步操作的预览能力，不是所有命令的通用参数。

遇到同名目录冲突时先检查来源：--force 只对允许覆盖的受管理目标有效，不会接管未知目录或其他来源。恢复记录前保留本地文件与 metadata；不要删除整个 ~/.skillhub，其中还存有其他实例凭证和安装记录。

安装

bash

# 通过 npm 全局安装
npm install -g @astron-team/skillhub

# 或使用 npx 直接运行（无需安装）
npx @astron-team/skillhub@latest version

# 或通过 Bun 全局安装
bun add -g @astron-team/skillhub

快速开始

bash

# 登录
skillhub login

# 搜索技能
skillhub search pdf

# 安装技能到 Agent 目录
skillhub install pdf-parser --agent codex

# 查看已安装技能
skillhub list

# 发布技能
skillhub publish ./my-skill --namespace myspace

Registry 配置

当前生效的 registry 按以下优先级解析：

--registry <url> 命令行参数
SKILLHUB_REGISTRY 环境变量
用户配置文件 ~/.skillhub/config.json 中的 registry 字段
默认值 https://skill.xfyun.cn

bash

# 临时使用其他 registry
skillhub search pdf --registry https://skillhub.example.com

# 通过环境变量设置（Linux/macOS）
export SKILLHUB_REGISTRY=https://skillhub.example.com

Windows PowerShell:

powershell

$env:SKILLHUB_REGISTRY="https://skillhub.example.com"

Windows CMD:

cmd

set SKILLHUB_REGISTRY=https://skillhub.example.com

认证

Token 按以下优先级解析：

--token <token> 命令行参数
SKILLHUB_TOKEN 环境变量
~/.skillhub/credentials.json 中存储的 token（按 registry 区分）

没有从命令行、环境变量或该注册中心保存记录读取到 Token 时，skillhub login 才使用 OAuth Device Flow；读取到无效 Token 时不会自动回退：打开验证页面并显示用户码，完成浏览器授权后保存凭证。无浏览器终端可用 skillhub login --no-open；自动化使用 API token。

bash

# 使用 API token 登录
skillhub login --token sk_xxx

# 指定 registry 登录
skillhub login --token sk_xxx --registry https://skillhub.example.com

login 会验证 token 有效性，然后将 token 存储到 ~/.skillhub/credentials.json，同时将 registry 写入 ~/.skillhub/config.json。

API Token 请求被拒绝时，CLI 会显示服务端返回的具体原因和 Request ID。排查问题时可使用该 ID 对照服务端日志；非 API Token 的授权失败仍只显示通用信息。

查看当前身份

bash

skillhub whoami

# 指定 registry 查看
skillhub whoami --registry https://skillhub.example.com

# 临时使用其他 token
skillhub whoami --token sk_other

登出

bash

skillhub logout

# 登出指定 registry
skillhub logout --registry https://skillhub.example.com

登出只删除对应 registry 的 token，保留 registry 配置和安装记录。

搜索

bash

# 关键词搜索
skillhub search pdf

# 列出所有技能（空字符串查询）
skillhub search "" --limit 50

# JSON 输出
skillhub search pdf --json

输出格式：namespace/slug version summary

安装技能

安装坐标支持裸 slug（默认解析到 global）和三种等价的显式 namespace 形式。显式坐标与 --namespace 同时出现时，两者必须一致。

bash

# 安装到自动探测的 Agent 目录
skillhub install pdf-parser

# 等价的 namespace 坐标
skillhub install team/my-skill
skillhub install @team/my-skill
skillhub install team--my-skill

# 显式指定安装范围
skillhub install pdf-parser --scope user
skillhub install pdf-parser --scope project --agent codex

# 为裸 slug 指定 namespace
skillhub install pdf-parser --namespace myspace

# 指定版本
skillhub install pdf-parser --version 1.2.0

# 安装到指定 Agent
skillhub install pdf-parser --agent codex

# 安装到 AStudio 的固定用户级目录
skillhub install pdf-parser --agent astudio

# 安装到 Pi 的用户级目录（添加 --scope project 可安装到项目级目录）
skillhub install pdf-parser --agent pi

# 安装到 DeepSeek Harness（项目级安装请在仓库根目录执行）
skillhub install pdf-parser --agent dsh

# 安装到多个 Agent
skillhub install pdf-parser --agent codex --agent claude-code

# 安装到自定义目录
skillhub install pdf-parser --dir ~/.claude/skills

# 强制覆盖已存在的安装
skillhub install pdf-parser --force

安装目标解析

CLI 按以下逻辑确定安装位置：

指定 --dir：安装到该目录，agent 标记为 custom。--dir 与 --scope、--agent 互斥。
指定 --scope user|project：探测限定在该 scope 内。
- 同时指定 --agent <profile>：直接安装到该 profile 对应 scope 的 skills 目录。
- 未指定 --agent：只探测该 scope 下已存在的 skills 目录。在交互式 user scope 下，始终额外提供 generic 目标（<home>/.agents/skills/），可单独选择或与已探测目标同时选择。
- 该 scope 下未探测到 → fallback：--scope user 回退到 <home>/.agents/skills/，--scope project 回退到 <cwd>/.agents/skills/。
指定 --agent（无 --scope）：安装到对应 Agent 的 skills 目录（沿用现有行为，不变）。
三者均未指定：
- 交互模式（stdin 和 stdout 都是 TTY 且未传 --json）：先交互式询问 user 还是 project scope，再按 --scope 规则继续。
- 非交互模式：自动扫描当前目录探测已存在的 Agent 配置目录。1 个 → 直接安装；多个 → 报错；未探测到 → 回退到 <cwd>/.agents/skills/。

--dir 不能与 --scope 或 --agent 同时使用。

安装路径

大多数 Agent 都有项目级和用户级两个 skills 目录。--scope user|project 决定使用哪一个。AStudio 仅使用固定的用户级目录。

Agent	项目级路径	用户级路径
`astudio`（AStudio）	不支持	`~/.acode/skills/`
`claude-code`	`<project>/.claude/skills/`	`~/.claude/skills/`
`codex`	`<project>/.codex/skills/`	`~/.codex/skills/`
`cursor`	`<project>/.cursor/skills/`	`~/.cursor/skills/`
`dsh`（DeepSeek Harness）	`<project>/.dsh/skills/`	`~/.dsh/skills/`
`github-copilot`	`<project>/.github-copilot/skills/`	`~/.github-copilot/skills/`
`gemini-cli`	`<project>/.gemini/skills/`	`~/.gemini/skills/`
`windsurf`	`<project>/.windsurf/skills/`	`~/.windsurf/skills/`
`kiro-cli`	`<project>/.kiro/skills/`	`~/.kiro/skills/`
`roo`	`<project>/.roo/skills/`	`~/.roo/skills/`
`trae`	`<project>/.trae/skills/`	`~/.trae/skills/`
`trae-cn`	`<project>/.trae-cn/skills/`	`~/.trae-cn/skills/`
`openhands`	`<project>/.openhands/skills/`	`~/.openhands/skills/`
`openclaw`	`<project>/.openclaw/skills/`	`~/.openclaw/skills/`
`opencode`	`<project>/.opencode/skills/`	`~/.opencode/skills/`
`kilo`	`<project>/.kilo/skills/`	`~/.kilo/skills/`
`pi`（Pi）	`<project>/.pi/skills/`	`~/.pi/agent/skills/`
`zcode`	`<project>/.zcode/skills/`	`~/.zcode/skills/`
fallback	`<project>/.agents/skills/`	`~/.agents/skills/`

对于自定义路径或不在列表中的 Agent 目录，使用 --dir 显式指定安装路径。交互式 user scope 下会与已探测 Agent 目标一同提供 generic 目标；当 ~/.acode/skills/ 存在时，选择器会显示 AStudio。当 --scope user|project 找不到匹配的 agent 目录时，CLI 会回退到上表的 _fallback_ 行。

DeepSeek Harness 从最近的 Git 仓库根目录解析项目技能，而 SkillHub CLI 的项目级 profile 使用当前目录。请在仓库根目录运行 --scope project --agent dsh。如果通过 DSH_HOME 覆盖了默认的 ~/.dsh，请改用 --dir "$DSH_HOME/skills" 安装。

安装后的文件结构

.codex/skills/pdf-parser/
├── ...                          # 技能包解压后的文件
└── .skillhub/
    └── metadata.json            # 安装元数据

metadata.json 内容示例：

json

{
  "registry": "https://skill.xfyun.cn",
  "namespace": "global",
  "slug": "pdf-parser",
  "version": "1.0.0",
  "agent": "codex",
  "installedAt": "2026-04-28T06:00:00.000Z"
}

技能安装后的使用与套装

安装命令只下载技能文件，不执行任务。打开目标项目并让 Agent 发现 SKILL.md，按技能说明配置依赖，再要求 Agent 使用该技能。套装请阅读安装与使用指南。

bash

# Replace with a real Suite coordinate
skillhub suite install @team/example-suite --scope project --agent codex
skillhub suite check @team/example-suite
skillhub suite upgrade @team/example-suite --check
skillhub suite upgrade @team/example-suite
skillhub suite remove @team/example-suite

团队工作区同步

sync 面向非 global 命名空间：pull 拉取选定技能，status/diff 检查变化，push 发布本地内容。默认工作区为当前目录的 .agents/skills。非交互 pull 必须显式选择 --skill；--check 只检查。

bash

skillhub sync pull --namespace team --check
skillhub sync pull --namespace team --skill example-skill
skillhub sync status --namespace team
skillhub sync diff --namespace team
skillhub sync push --namespace team --all --dry-run

本地管理

查看已安装技能

bash

# 列出所有已安装技能
skillhub list

# 按 Agent 过滤
skillhub list --agent codex

# 按多个 Agent 过滤
skillhub list --agent codex --agent claude-code

# 按目录过滤
skillhub list --dir ~/.codex/skills

# JSON 输出
skillhub list --json

删除技能

bash

# 裸 slug 删除所有 namespace 中的同名本地安装
skillhub remove pdf-parser

# 显式 namespace 坐标只删除该 namespace
skillhub remove myspace/pdf-parser
skillhub remove @myspace/pdf-parser
skillhub remove myspace--pdf-parser

# 使用 namespace 参数进行等价的精确本地删除
skillhub remove pdf-parser --namespace myspace

# 只删除指定 Agent 的安装
skillhub remove pdf-parser --agent codex

# 删除所有目标（跳过交互确认）
skillhub remove pdf-parser --all

# 删除远程技能（需要认证，会弹出确认提示）
skillhub remove pdf-parser --remote --namespace myspace

# 跳过远程删除确认
skillhub remove pdf-parser --remote --hard --namespace myspace

参数互斥规则：
--all 不能与 --agent 同时使用
--remote 不能与 --agent 或 --all 同时使用
非交互环境下远程删除必须加 --hard

重建本地清单

bash

skillhub doctor

doctor 执行以下操作：

扫描 <cwd>/.<agent>/skills/<slug>/.skillhub/metadata.json
按 registry + namespace + slug 分组
备份旧的 inventory.json（如果存在）
写入新的 inventory.json

版本按安装目标记录。doctor 报告恢复问题，不会下载或升级技能。

发布

bash

# 发布目录（自动打包为 zip）
skillhub publish ./my-skill --namespace myspace

# 发布已有的 zip 文件
skillhub publish ./my-skill.zip --namespace myspace

# 指定可见性
skillhub publish ./my-skill --namespace myspace --visibility private

可见性选项：

public（默认）— 所有人可见
namespace-only — 仅 namespace 成员可见
private — 仅自己可见

提交被服务端接受后会输出当前状态和技能详情页 URL。SCANNING、PENDING_REVIEW 表示异步处理尚未完成；请在详情页确认最终发布状态。

自更新

bash

# 检查是否有新版本
skillhub update --check

# 执行更新
skillhub update

更新机制：

通过 npm 全局安装：自动执行 npm install -g @astron-team/skillhub@latest
通过 Bun 全局安装：自动执行 bun add -g @astron-team/skillhub@latest
通过 npx 运行：提示手动更新命令
未知安装方式：提示手动更新

环境变量

变量	说明	优先级
`SKILLHUB_REGISTRY`	默认 registry URL	低于 `--registry` 参数
`SKILLHUB_TOKEN`	API token	低于 `--token` 参数，高于存储的 token

本地文件结构

~/.skillhub/
├── config.json           # 用户配置（registry、defaultAgent 等）
├── credentials.json      # API tokens（按 registry 存储，权限 0600）
└── inventory.json        # 已安装技能清单

config.json

json

{
  "registry": "https://skill.xfyun.cn",
  "defaultAgent": "codex",
  "lastUpdateCheckAt": "2026-04-28T06:00:00.000Z"
}

credentials.json

json

{
  "tokens": {
    "https://skill.xfyun.cn": "sk_xxx",
    "https://skillhub.example.com": "sk_yyy"
  }
}

inventory.json

CLI 管理的安装记录，不应手工编辑。每个安装目标分别记录版本、fingerprint 和来源；兼容客户端在需要时迁移旧记录。备份用于恢复核查，不代表可以直接覆盖更新后的 inventory。

当前主分支代码包含使用 inventory v3 的 DSH 启用/停用能力。不要假设已发布 CLI 已支持，也不要混用不兼容写入端。CLI 没有 enable/disable 命令；该增量中，CLI --force 不能升级停用目标，doctor 也不会仅凭孤立的 SKILL.md.disabled 重建停用来源。启停由兼容版本的 DSH 管理，使用时以配套发行说明为准。

JSON 输出

所有命令都支持 --json 参数，输出机器可读的 JSON 格式：

bash

skillhub search pdf --json
skillhub list --json
skillhub whoami --json
skillhub install pdf-parser --json
skillhub remove pdf-parser --json
skillhub doctor --json

成功响应格式：

json

{
  "ok": true,
  ...
}

错误响应格式：

json

{
  "ok": false,
  "message": "error message",
  "exitCode": 2,
  "details": {
    "registry": "https://skill.xfyun.cn",
    "next": "run `skillhub login`"
  }
}

退出码

退出码	说明
0	成功
1	通用错误
2	认证失败
3	网络错误
4	文件系统错误
5	参数错误
6	校验或安装来源冲突

命令参考

help

bash

skillhub help
skillhub help install

显示帮助信息。

version

bash

skillhub version
skillhub version --json

显示 CLI 版本。

bash

skillhub login [--no-open] [--token <token>] [--registry <url>] [--json]

保存 token 和 registry 配置。

CLI 以非破坏方式更新 ~/.skillhub/credentials.json 和 ~/.skillhub/config.json：只修改自己使用的 tokens 和 registry 字段，保留其他兼容工具写入的未知字段。

logout

bash

skillhub logout [--registry <url>] [--json]

删除指定 registry 的 token。

whoami

bash

skillhub whoami [--registry <url>] [--token <token>] [--json]

验证当前 token 并显示用户信息。

search

bash

skillhub search <query> [--registry <url>] [--limit <n>] [--json]

搜索已发布的技能。

install

bash

skillhub install <coordinate> [options]

<coordinate> 支持裸 slug（my-skill，解析为 global/my-skill）以及 team/my-skill、@team/my-skill、team--my-skill 三种等价的显式 namespace 形式。裸 slug 可通过 --namespace team 选择非 global namespace；显式坐标可以同时传入相同的 --namespace，但冲突值会作为用法错误被拒绝。

选项：

--scope <user|project> — 安装范围（不传时：TTY 模式下交互式询问，非 TTY 模式沿用现有探测逻辑）
--namespace <slug> — 为裸 slug 指定 namespace
--version <v> — 版本（默认最新版本）
--agent <profile> — Agent 配置（可重复）
--dir <path> — 自定义安装目录（与 --scope、--agent 互斥）
--force — 覆盖已存在的安装
--registry <url> — Registry URL
--token <token> — API token
--json — JSON 输出

list

bash

skillhub list [options]

选项：

--agent <profile> — 按 Agent 过滤（可重复）
--dir <path> — 按目录过滤
--registry <url> — Registry URL
--json — JSON 输出

remove

bash

skillhub remove <coordinate> [options]

选项：

--agent <profile> — 按 Agent 过滤（可重复）
--all — 删除所有目标
--remote — 删除远程技能
--hard — 跳过远程删除确认
--namespace <slug> — 本地或远程删除的 namespace
--registry <url> — Registry URL
--token <token> — API token
--json — JSON 输出

显式命名空间坐标（team/my-skill、@team/my-skill、team--my-skill）或 --namespace team 只删除该 namespace 中的本地安装。为保持兼容，裸 slug 会删除当前 registry 中所有 namespace 下的同名本地安装。

doctor

bash

skillhub doctor [--json]

扫描项目目录，重建本地清单。

publish

bash

skillhub publish <path> [options]

选项：

--namespace <slug> — Namespace
--visibility <v> — 可见性（public | namespace-only | private）
--registry <url> — Registry URL
--token <token> — API token
--json — JSON 输出

suite

bash

skillhub suite <install|check|upgrade|remove> <coordinate> [options]

install 支持 --version、--scope、--agent、--dir；install 和 upgrade 支持 --force。upgrade --check 预览变更。各操作支持 --registry、--token、--json。详见套装指南。

sync

bash

skillhub sync <pull|status|diff|push> --namespace <slug> [options]

先运行 skillhub help sync 查看选择、工作区和发布参数；发布前使用 push --dry-run 验证。

update

bash

skillhub update [--check] [--json]

检查或执行 CLI 自更新。

安全说明

Token 只存储在用户目录 ~/.skillhub/credentials.json
在 Linux/macOS 上，凭据文件权限自动设置为 0600
不会将 token 写入任何项目本地文件
远程删除操作需要显式确认或 --hard 参数
remove 命令会验证路径安全性，防止删除非技能目录

故障排查

认证失败

bash

# 验证 token 是否有效
skillhub whoami

# 重新登录
skillhub login --token sk_xxx

网络错误

bash

# 检查 registry 是否可访问
curl 'https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1'

# 使用其他 registry
skillhub search test --registry https://skillhub.example.com

安装目录冲突

bash

# 使用 --force 覆盖
skillhub install pdf-parser --force

# 或先删除再安装
skillhub remove pdf-parser
skillhub install pdf-parser

清单损坏

bash

# 重建清单
skillhub doctor

本地开发验证

如果你在本地开发 SkillHub，可以这样验证 CLI：

bash

# 1. 构建 CLI
cd cli
bun install
bun run build
bun link

# 2. 启动本地后端
cd ..
make dev-all

# 3. 配置 CLI 连接本地服务（Linux/macOS）
export SKILLHUB_REGISTRY=http://localhost:8080

# Windows PowerShell:
# $env:SKILLHUB_REGISTRY="http://localhost:8080"

# Windows CMD:
# set SKILLHUB_REGISTRY=http://localhost:8080

# 4. 测试命令
skillhub search test
skillhub install example-skill --agent codex
skillhub list

许可证

Apache-2.0

CLI 使用参考 ​

选择正确的管理对象 ​

自动化和错误处理 ​

安装 ​

快速开始 ​

Registry 配置 ​

认证 ​

登录 ​

查看当前身份 ​

登出 ​

搜索 ​

安装技能 ​

安装目标解析 ​

安装路径 ​

安装后的文件结构 ​

技能安装后的使用与套装 ​

团队工作区同步 ​

本地管理 ​

查看已安装技能 ​

删除技能 ​

重建本地清单 ​

发布 ​

自更新 ​

环境变量 ​

本地文件结构 ​

config.json ​

credentials.json ​

inventory.json ​

JSON 输出 ​

退出码 ​

命令参考 ​

help ​

version ​

login ​

logout ​

whoami ​

search ​

install ​

list ​

remove ​

doctor ​

publish ​

suite ​

sync ​

update ​

安全说明 ​

故障排查 ​

认证失败 ​

网络错误 ​

安装目录冲突 ​

清单损坏 ​

本地开发验证 ​

相关链接 ​

许可证 ​

CLI 使用参考

选择正确的管理对象

自动化和错误处理

安装

快速开始

Registry 配置

认证

登录

查看当前身份

登出

搜索

安装技能

安装目标解析

安装路径

安装后的文件结构

技能安装后的使用与套装

团队工作区同步

本地管理

查看已安装技能

删除技能

重建本地清单

发布

自更新

环境变量

本地文件结构

config.json

credentials.json

inventory.json

JSON 输出

退出码

命令参考

help

version

login

logout

whoami

search

install

list

remove

doctor

publish

suite

sync

update

安全说明

故障排查

认证失败

网络错误

安装目录冲突

清单损坏

本地开发验证

相关链接

许可证