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

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

官方参考：

• OpenClaw：Skills
• OpenClaw：ClawHub

1. Skill 是什么、装在哪里

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

2.SKILL.mdfrontmatter（openclaw 会解析的部分）

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

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

2.1metadata.openclaw常见字段

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

2.2 示例（摘自本仓库bundled-skills）

需要 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: ""
---

2.3description怎么写（给模型「何时调用」用）

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

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

3. 本地开发流程

3.1 目录放哪

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

3.2 脚本与依赖

• 脚本放在 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 后找不到。

3.3 自检清单

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

4. 打进 OpenClaw 安装包（bundled-skills）

4.1 同步到src-tauri/bundled-skills/

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。

4.2 静默更新已安装用户的内置副本

应用启动时会对比：

• 包内 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 注释）。

5. 发布到 ClawHub（上传 Skill）

5.1 CLI

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-* 系列）。

5.2 网页上传

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

5.3 与本仓库相关的限制与坑

6. 与本仓库其他脚本的关系（按需）

7. 小结检查清单

开发

• 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开发与发布内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

最新评论