skillhub-publish — 一键发布技能到 SkillHub
用途
将本地 Skill 目录发布到 SkillHub 社区平台（https://skillhub.cn）。封装登录验证、frontmatter 字段检查、文件打包和 CLI 上传全流程。
何时使用
- 用户要求"上传技能"、"发布技能"、"publish skill"
- 用户提到 SkillHub、skillhub 并希望上传
- 用户完成技能开发后想分享到社区
前置条件
- 已安装 SkillHub CLI（位于
~/.skillhub/cli/skills_store_cli.py） - 拥有 SkillHub API Token（
skh_开头） - Python 3.x 可用（推荐使用
C:\Users\wlb\.workbuddy\binaries\python\versions\3.13.12\python.exe）
标准发布流程（严格按顺序执行）
阶段 1：确认 SkillHub CLI 已安装
检查 ~/.skillhub/cli/skills_store_cli.py 是否存在：
ls ~/.skillhub/cli/skills_store_cli.py
若不存在，执行安装：
node -e "
const https = require('https');
const fs = require('fs');
const path = require('path');
const dest = path.join(require('os').tmpdir(), 'skillhub-latest.tar.gz');
const file = fs.createWriteStream(dest);
https.get('https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/latest.tar.gz', (res) => {
res.pipe(file);
file.on('finish', () => { file.close(); console.log('Downloaded'); });
});
"
等待 3 秒后解压：
SH_TGZ=$(node -e "console.log(require('path').join(require('os').tmpdir(), 'skillhub-latest.tar.gz'))") && mkdir -p ~/.skillhub && cp "$SH_TGZ" ~/.skillhub/latest.tar.gz && cd ~/.skillhub && tar xzf latest.tar.gz && rm latest.tar.gz
阶段 2：登录 SkillHub
若用户已有 skh_ token，执行登录：
cd ~/.skillhub/cli && <PYTHON_PATH> skills_store_cli.py login --key "skh_<用户的token>"
登录成功会输出：✓ Logged in as @<handle> (userId=<id>)
凭证保存在 ~/.skillhub/credentials.json，后续发布无需再次登录。
重要：不要把 token 写入任何文件或日志，只在命令行临时使用。
阶段 3：检查并补全 SKILL.md frontmatter
SkillHub 要求 SKILL.md 的 YAML frontmatter 必须包含以下字段：
| 字段 | 要求 | 说明 |
|---|---|---|
slug |
必填 | kebab-case，3-128 字符，如 deploy-n8n |
version |
必填 | SemVer 格式，如 1.0.0 |
displayName |
必填 | 显示名称，如 "一键部署 n8n" |
name |
必填 | 技能标识符 |
description |
必填 | 技能描述 |
summary |
选填 | 简短摘要 |
用 Read 工具读取目标技能的 SKILL.md，检查 frontmatter 是否齐全。若缺少字段，用 Edit 工具补充。
slug 规则：只能小写字母、数字、连字符，必须以字母/数字开头和结尾。
version 规则：必须符合 SemVer（X.Y.Z 格式）。
阶段 4：检查文件合规性
SkillHub 对上传文件有限制：
- 禁止 .bat 文件：可执行脚本会被拒绝，需改名为 .txt
- 排除目录：.git、.idea、.vscode、node_modules、__pycache__
- 排除文件：*.pyc、.DS_Store、Thumbs.db
- 必须包含根目录的 SKILL.md
用 Glob 工具检查目标技能目录是否有 .bat 文件：
pattern: "**/*.bat"
path: <技能目录>
若有 .bat 文件，用 Bash 重命名为 .txt：
cd <技能目录> && mv assets/start-n8n.bat assets/start-n8n.txt
同时更新 SKILL.md 中对该文件的引用说明。
阶段 5：Dry-run 验证（可选但推荐）
cd ~/.skillhub/cli && <PYTHON_PATH> skills_store_cli.py publish "<技能目录>" --dry-run
输出 ✓ Dry-run passed: <slug>@<version> 表示验证通过。
阶段 6：发布上传
cd ~/.skillhub/cli && <PYTHON_PATH> skills_store_cli.py publish "<技能目录>" --changelog "<变更说明>"
成功输出：✓ Published: skillId=<id> status=<status>
记录返回的 skillId，告知用户。
阶段 7：验证发布结果
可在 SkillHub 官网 https://skillhub.cn 的"我的技能"页面查看审核状态。
新发布的技能需要通过平台审核后才会公开上架。
常见错误速查表
| 症状 | 原因 | 解决 |
|---|---|---|
未登录。请先执行: skillhub login |
未登录或凭证过期 | 执行阶段 2 重新登录 |
token 必须以 skh_ 开头 |
token 格式错误 | 确认 token 前缀是 skh_ 不是 sk_ |
SKILL.md 缺少 slug |
frontmatter 缺字段 | 执行阶段 3 补全 |
slug 不合法 |
slug 格式错误 | 改为 kebab-case 小写 |
version 不是合法 SemVer |
版本号格式错 | 改为 X.Y.Z 格式 |
SKILL.md 缺少 displayName |
frontmatter 缺字段 | 补充 displayName |
| 上传被拒（文件类型） | 含 .bat 等可执行文件 | 执行阶段 4 改名为 .txt |
| HTTP 401 / invalid_credentials | token 无效或过期 | 到 skillhub.cn 重新生成 token |
| HTTP 429 | 限流 | 稍后重试，平台有按 token/IP 限流 |
资源引用
scripts/publish.sh— 封装发布流程的辅助脚本（可选）references/skillhub-fields.md— SKILL.md frontmatter 字段完整规范
技术细节
- SkillHub API Host:
https://api.skillhub.cn - 发布端点:
POST /api/v1/community/skills/publish - 认证方式:
Authorization: Bearer skh_xxx - 上传格式: multipart/form-data（payload JSON + 多个 files part）
- 凭证存储:
~/.skillhub/credentials.json - CLI 版本: 见
~/.skillhub/cli/version.json
卸载/登出
# 登出（清除本地凭证）
cd ~/.skillhub/cli && <PYTHON_PATH> skills_store_cli.py auth logout
