SkillHub 教程 - AI Skills 安装与使用指南

通过 CLI 和 Agent 发布 Skill

本指南会带你完整跑一遍：注册账号 → 实名认证 → 创建 API Token → 安装 CLI → 发布第一个 Skill。预计 15 分钟。每一步都会告诉你"应该看到什么"，遇到不一致的情况可通过页面右侧「建议反馈」入口告知我们。

不需要懂编程，所有命令复制粘贴即可执行。

你需要准备什么

项	说明
一个手机号	注册时接收 6 位短信验证码
一台 Mac 或 Linux 电脑	Windows 用户请使用 WSL；本指南以 Mac 为例
浏览器	用于注册账号、实名认证、创建 API Token
终端	用于执行 `skillhub` 命令（Mac 自带"终端"应用）

什么时候该用 CLI？

不同场景下的推荐方式：

场景	推荐方式
一次性发布、只发一两个 Skill	网页就够了
经常迭代、改完就想发	CLI
想接 CI / GitHub Actions 自动发布	CLI
团队协作、版本要走 git	CLI

如果你属于后面三种场景，建议跟随本指南走完 CLI 全流程。

第一步：注册账号 + 实名认证

浏览器打开 https://skillhub.cn 并点右上角「登录 / 注册」。
选择手机号验证码登录，输入手机号 → 获取验证码 → 输入 6 位数字。首次登录会自动注册账号；登录成功后右上角会显示你的头像或用户名。
点右上角头像 → 个人中心，找到「实名认证」入口，按提示完成人脸核身（可使用手机扫二维码刷脸）。
看到实名状态变为「已认证」，即可进入下一步。未完成实名将无法创建 API Token，也无法发布 Skill。

第二步：创建 API Token

API Token 是给命令行工具用的"机器人凭证"，让 CLI 在你不输入网页密码的情况下完成发布。

保持在浏览器登录态，点右上角头像 → 个人中心，左侧菜单进入「API keys」（直链 /dashboard/keys）。
点页面左下角的「创建 API key」按钮。
在弹窗里填写一个能让你认出来的名称，例如 MacBook 或 测试用。留空也可以，系统会自动设为 CLI token。
点「创建」，弹窗会一次性显示完整 Token，类似：skh_4f3c2b1e9a8d7c6f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e。这是唯一一次能看到完整 Token 的机会，请立刻复制保存到便签或密码管理器。
不慎关闭弹窗或丢失 Token 也不必担心：回到列表把这把删掉，重新创建一把即可。

第三步：安装 SkillHub CLI

在终端执行以下命令，安装 CLI（不附带预置 Skill 集合）：

curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only

安装完成后，首次使用还需要让终端能找到 skillhub 命令：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

执行下面的命令验证安装是否成功：

skillhub --version

看到版本号（例如 skillhub 2026.6.12）即代表安装成功。如果提示 command not found: skillhub，请新开一个终端窗口重试；仍不行则重新执行上面的安装命令。

把第二步复制的 skh_xxx 替换到下面命令中的对应位置，然后在终端执行：

skillhub login \
  --key 你刚才复制的完整Token \
  --host https://api.skillhub.cn

看到 ✓ Logged in as @你的handle (userId=xxx) 即登录成功。

再执行一次身份校验：

skillhub auth whoami

应当输出 userId / handle / role 三行信息，与你账号一致。

第五步：准备 Skill 并发布

完成以上流程后，CLI 发布的前置链路已全部打通。接下来准备好你的 Skill 文件夹，确保根目录下的 SKILL.md 头部包含以下 frontmatter，即可进行发布：

---
slug: hello-skillhub-zhangsan
displayName: Hello SkillHub
version: 1.0.0
summary: 我的第一个 Skill
license: MIT
---

参数含义

参数	含义
`slug`	Skill 的唯一标识，全网唯一
`displayName`	Skill 的对外展示名称
`version`	Skill 的版本号
`summary`	Skill 的简介与概述
`license`	Skill 的开源许可证

⚠️ slug 必须全网唯一。请把示例中的 hello-skillhub-zhangsan 改成你自己专属的名字（例如带上你的 handle），否则发布时会因冲突失败。

正式发布前，建议先用 --dry-run 做本地预检。该指令不会真正发布，只检查格式，几秒钟出结果：

skillhub publish ~/my-first-skill --dry-run

其中 my-first-skill 替换为你的 Skill 文件夹名。看到 ✓ Dry-run passed: <slug>@1.0.0 表示本地校验通过。如果出现 Error: SKILL.md 缺少 ...，请回去检查 frontmatter 字段是否漏填，补齐后重试。

本地预检通过后，正式发布：

skillhub publish ~/my-first-skill --changelog "首次发布"

其中 my-first-skill 替换为你的 Skill 文件夹名；--changelog 用于填写本次变更说明，首次发布填「首次发布」即可。

看到 ✓ Published: skillId=xxxxx status=pending_review 即发布成功，进入审核流程。审核完成后回到浏览器访问对应详情页，或前往个人中心 → 我的 Skill 查看状态。

更新 Skill

更新 Skill 与首次发布流程一致：准备好最新的 Skill 文件，保持 slug 不变，其他字段（如 version、displayName、summary 等）按需修改，然后在 --changelog 后填写本次的版本变更说明即可：

skillhub publish ~/my-first-skill --changelog "修复 xxx，新增 yyy"

通过与 Agent 自然对话发布 Skill

除了 CLI 发布，我们也支持直接通过与 Agent 自然对话发布 Skill。在接入 SkillHub 的 Agent 客户端里，你可以直接把下面这条指令复制发送给 AI，剩下的事交给它：

根据 https://skillhub.cn/ai/release.md 把 my-first-skill（你要发布的 Skill 文件）发布到 SkillHub。

把 my-first-skill 替换成你本地 Skill 文件夹的实际路径或名称即可。Agent 会自动读取发布规范，完成参数校验、登录态确认和发布请求。

常见问题

Q1：终端报 command not found: skillhub？

先执行 source ~/.zshrc 重新加载环境变量；仍不行可使用完整路径 ~/.local/bin/skillhub --version 验证安装是否成功。

Q2：401 invalid api key？

Token 已被撤销或失效。回到「个人中心 → API keys」重新创建一把，再执行 skillhub login --key <新token> --host ...。

Q3：403 请先完成实名认证？

回浏览器完成实名认证后再重试发布。

Q4：409 slug 已被其他用户占用？

把 SKILL.md 中的 slug 改成全网唯一的标识（建议带上你的 handle 作为前缀或后缀）。

Q5：429 请求过于频繁？

触发了平台限频，等约 1 分钟后重试即可。

Q6：发布成功了但详情页显示"未找到"？

通常是审核还在进行中。可前往个人中心 → 我的 Skill 查看实时状态，审核通过后详情页会自动可见。

Q7：之前装过老版本 CLI 想完全重装？

# 完全卸载老版本
rm -rf ~/.skillhub
rm -f ~/.local/bin/skillhub
# 然后重新执行第三步的安装命令

更多问题可通过页面右侧「建议反馈」入口告知我们。