OpenClaw Skill开发与发布全流程解析

目录

• 1. Skill 是什么、装在哪里
• 2.SKILL.mdfrontmatter（openclaw 会解析的部分）
• 2.1metadata.openclaw常见字段
• 2.2 示例（摘自本仓库bundled-skills）
• 2.3description怎么写（给模型「何时调用」用）
• 3. 本地开发流程
• 3.1 目录放哪
• 3.2 脚本与依赖
• 3.3 自检清单
• 4. 打进 OpenClaw 安装包（bundled-skills）
• 4.1 同步到src-tauri/bundled-skills/
• 4.2 静默更新已安装用户的内置副本
• 5. 发布到 ClawHub（上传 Skill）
• 5.1 CLI
• 5.2 网页上传
• 5.3 与本仓库相关的限制与坑
• 6. 与本仓库其他脚本的关系（按需）
• 7. 小结检查清单

本文面向在本仓库中开发、调试、打包进应用、发布到 ClawHub 的 OpenClaw Skill。

官方参考：

• OpenClaw：Skills
• OpenClaw：ClawHub

• 每个 Skill 是一个目录，根目录必须有 SKILL.md（YAML frontmatter + Markdown 正文）。
• 用户机器上，TsClaw / OpenClaw 使用的安装路径为 ~/.openclaw/skills/<slug>/（Windows 下为配置目录下的 skills<slug>，与 src-tauri 中 get_skills_dir() 一致）。
• 正文和示例命令里通常写 node ~/.openclaw/skills/<slug>/scripts/...，便于代理在运行时找到脚本。

TsClaw 会从 SKILL.md 里读出 name、description、version（可选） 以及 metadata.openclaw，用于：

• 技能列表、搜索展示；
• 判断是否缺 环境变量 / API Key（primaryEnv、requires.env、optional.env）；
• 判断是否缺 PATH 二进制（requires.bins），并给出 missingBins；
• 可选 install：声明如何安装缺失依赖（brew / npm 等），供安装器/UI 使用。

与仓库内实现一致（见 src-tauri/src/commands/skills.rs 中 OpenClawMetaRaw / SkillMetadata）：

字段	含义
primaryEnv	与 skills.entries[slug].apiKey 对应的主环境变量名（可为空字符串表示不绑单一 Key）
requires.env	必填环境变量列表
optional.env	可选环境变量列表
requires.bins	必须在 PATH 中的可执行文件名列表
install	可选，SkillInstallSpec 数组（id / kind / formula / bins / label / os 等）

需要 API Key 的 Skill：

---
name: openclaw-translate
description: >
  多语言翻译…… Use when: … NOT for: …
metadata:
  openclaw:
    primaryEnv: BAIDU_TRANSLATE_APPID
    requires:
      env:
        - BAIDU_TRANSLATE_APPID
        - BAIDU_TRANSLATE_SECRET
---

纯本地、无 Key 的 Skill：

---
name: tianshu-xhs-note
description: >
  … Use when: … NOT for: …
metadata:
  openclaw:
    primaryEnv: ""
---

本仓库内 Skill 的惯例（可与 OpenClaw 文档一起对照）：

1. 一句话能力 + Use when: 典型用户说法/场景。
2. 可选 NOT for: 写清不要误用的边界，减少错误触发。
3. 正文里再写 When to Run、Workflow、参数表、示例命令，与 frontmatter 呼应。

• 本仓库：常在 skills/<slug>/ 下迭代（与 scripts/download-bundled-skills.mjs 的「项目内副本」逻辑一致）。
• 真机联调：把同名目录拷到 ~/.openclaw/skills/<slug>/，或安装一次后再改文件，保证 OpenClaw / 天树 读到的就是你在测的版本。

• 脚本放在 scripts/，用 Node 的可执行方式调用（本仓库大量 Skill 已 Node 化，见 skills/SKILLS_ANALYSIS.md）。
• 若需要 npm 依赖，在 Skill 目录放 package.json，用户或应用侧需在对应目录执行 npm install（例如 wechat-article-search 对 cheerio 的处理，download-bundled-skills.mjs 里有兜底注入 package.json 的逻辑）。
• 文档中的示例路径统一为 ~/.tsclaw/skills/...，避免只写相对路径导致代理换 cwd 后找不到。

• SKILL.md frontmatter 能被解析：metadata.openclaw 存在且 YAML 合法。
• name 与目录名 / ClawHub slug 一致或符合你的发布命名约定。
• 在目标平台实际跑一遍脚本（macOS / Windows 路径、引号转义、--text vs --file）。

1. 将 slug 加入 scripts/download-bundled-skills.mjs 里的 SKILLS 数组（若需要随发行版打包）。
2. 运行（需网络拉 ClawHub 时）：npm run skills:bundled 或 node scripts/download-bundled-skills.mjs。
3. 本地优先：脚本会优先从 ~/.openclaw/skills/<slug> 复制，其次 仓库/skills/<slug>，都没有再请求 ClawHub。适合你先本地改好再一键拷进 bundled-skills。

应用启动时会对比：

• 包内 src-tauri/bundled-skills/BUNDLED_SKILLS_REVISION 的修订号；
• 用户目录 ~/.openclaw/.bundled-skills-sync-app-version 里记录的上次同步修订。

仅当你希望已安装用户在不升应用 semver 的情况下覆盖内置 Skill 时：递增 BUNDLED_SKILLS_REVISION（当前实现见 skills.rs 中 schedule_auto_install_bundled_skills 注释）。

1. 安装并登录：npm install -g clawhub，执行 clawhub login。
2. 在 Skill 目录或仓库路径执行发布，例如本仓库脚本中的形式：

clawhub publish "skills/${slug}" 
  --slug "$slug" 
  --name "显示名称" 
  --version 1.0.0 
  --changelog "说明本次变更"

或使用 npx（见 scripts/publish-aiznt-skills.mjs）：

npx --yes clawhub@latest publish <目录> --slug ... --name ... --version ... --changelog ... --tags ...

部分 Skill 使用目录内 clawhub.json 维护 name / version / tags 等，再被发布脚本读取（aiznt-* 系列）。

ClawHub 支持在浏览器上传压缩包：https://clawhub.ai/upload（需按站点要求登录，如 GitHub）。

问题	说明与处理
新 slug 限流	仓库内注释：每小时最多约 5 个新 slug；批量发布用 publish-student-skills-clawhub.sh / publish-aiznt-skills.mjs 时已说明失败时隔一段时间再跑或 –from 跳过已成功的。
HTTP 429	download-bundled-skills.mjs 对下载有重试；发布端若遇限流同样需等待 Retry-After 或错峰。
版本已存在	提高 –version 或 clawhub.json 里的 version 后再发。
ZIP 目录结构	ClawHub 下载解压后若只有一层子目录（名为 slug 或 skill），应用侧会上移一层；本地打包时避免多嵌套导致 SKILL.md 不在根目录。
metadata 格式	TsClaw 用 YAML 解析 frontmatter；metadata 可为嵌套 YAML 或部分场景下的 JSON 字符串（见 read_skill_metadata）。若解析失败，设置页可能看不到 Key/bin 提示；可参考已上架 Skill 或 tianshu-qiniu-upload README 中的说明。

脚本	作用
scripts/publish-student-skills-clawhub.sh	一批 tianshu-* 学生向 Skill 发布到 ClawHub（未写进默认 bundled 列表时可单独发）。
scripts/publish-aiznt-skills.mjs	发布 aiznt-* 系列，支持 –dry-run、–from slug。
npm run skills:baoyu	从 JimLiu/baoyu-skills 同步 baoyu-* 到 bundled-skills（另一路技能源）。
npm run bundles:sync	同步 bundled skills、钉钉插件、openclaw tgz 等（发布前整包准备时常用）。

开发

• SKILL.md 含 metadata.openclaw，且 description 含 Use when / NOT for（按需）
• 脚本路径、环境变量名与文档一致
• 在 ~/.tsclaw/skills/<slug> 下实测通过

进包

• slug 已加入 download-bundled-skills.mjs 的 SKILLS（若需要内置）
• 需要静默推送更新时递增 BUNDLED_SKILLS_REVISION

上架 ClawHub

• clawhub login 成功，版本号/changelog 正确
• 注意新 slug 与小时间窗口限流，失败时分批重试

到此这篇关于OpenClaw Skill开发与发布全流程解析的文章就介绍到这了,更多相关OpenClaw Skill开发与发布内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！