本文面向在本仓库中开发、调试、打包进应用、发布到 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.md frontmatter（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.1 metadata.openclaw 常见字段

与仓库内实现一致（见 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 等）

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.3 description 怎么写（给模型「何时调用」用）

本仓库内 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 与本仓库相关的限制与坑

问题	说明与处理
新 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 中的说明。

---

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

脚本	作用
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 等（发布前整包准备时常用）。

---

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 与小时间窗口限流，失败时分批重试

---