marila-skill-publish

Original source / Raw SKILL.md

---
name: marila-skill-publish
description: 用于发布和更新 OpenClaw 技能到 ClawHub，并同步 GitHub Release。用户提到“发布技能”“发到 ClawHub”“发布这个 skill”“写完就发布”“上线这个技能”等场景时使用。包含完整发布步骤、版本规范、发布前检查清单、GitHub Release 同步规则和常见问题处理。
version: 1.0.7
metadata:
  openclaw:
    requires:
      bins:
        - clawhub
        - git
        - gh
    homepage: https://github.com/aliramw/dingtalk-ai-table
---

# ClawHub 技能发布流程

本文档总结了从 0 到发布一个 ClawHub 技能的完整流程和经验。

## 📋 前置要求

- Node.js >= 18
- `clawhub` CLI (`npm install -g clawhub`)
- Git
- GitHub CLI (`gh`)
- ClawHub 账号（已登录）
- GitHub 账号（用于 push 和 GitHub Release）

## 🧰 环境检查与补装

先检查命令是否存在：

```bash
which git
which gh
which clawhub
```

如果缺命令：

```bash
# macOS（推荐）
brew install git gh
npm install -g clawhub

# Ubuntu / Debian
sudo apt update
sudo apt install -y git gh
npm install -g clawhub
```

验证：

```bash
git --version
gh --version
clawhub --version
```

## 🔐 GitHub 鉴权与 Git 初始化

如果用户还没登录 GitHub，先做这个：

```bash
# 登录 GitHub CLI
gh auth login

# 验证登录状态
gh auth status
```

如果用户本机 Git 还没初始化身份，先配置：

```bash
git config --global user.name "你的名字"
git config --global user.email "[email protected]"
```

如果仓库还没绑远程：

```bash
git remote add origin https://github.com/<user>/<repo>.git
# 或
# git remote add origin [email protected]:<user>/<repo>.git
```

发布前最少确认这 4 件事：

```bash
git status
git remote -v
gh auth status
clawhub whoami
```

## ✅ 发布顺序（必须按此顺序，不能错）

发布前，**先检查** `references/clawhub-review-checklist.md`，确认元数据、README、脚本行为、凭证声明和示例参数已经一致。

1. **确定版本号** — 同步修改 `SKILL.md` 和 `package.json` 的 version 字段
2. **更新 CHANGELOG.md** — 在顶部追加新版本记录
3. **先过一遍 checklist** — 特别检查 `requires.bins` / `requires.env` / `primaryEnv` / 本地文件行为说明
4. **push + GitHub Release** — `git add -A && git commit && git push`，然后 `gh release create v0.x.x --title "v0.x.x" --notes "..."`
5. **发布到 ClawHub** — `clawhub publish <路径> --slug <名> --version x.x.x --changelog "..."`
6. **如需立即让当前 agent 使用最新技能定义，再手动同步到 agent 工作空间** — `cp <技能目录>/SKILL.md ~/.openclaw/workspace/skills/技能名/SKILL.md`

**硬规则：** 以后凡是发布 OpenClaw 技能，**每次 ClawHub 发布都必须同步创建对应的 GitHub Release**。不允许只发技能不发 release。

**新增硬规则：** 发布前必须过一遍 `references/clawhub-review-checklist.md`。尤其是带脚本、凭证、工作区文件读写的技能，不检查就发，极容易被 ClawHub 审核打回。

**敏感操作提示：** 同步到 `~/.openclaw/workspace/skills` 属于对 agent 工作区的写操作，只应在受信任环境中显式执行，不应在公共或不受信任场景下默认执行。

---

## 🚀 完整流程

### 1. 准备技能文件夹

```bash
# 创建技能目录
mkdir -p ~/my-skill
cd ~/my-skill

# 初始化 Git
git init
```

### 2. 创建必需文件

#### SKILL.md（必需）

```markdown
---
name: my-skill
description: 简短描述技能功能
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - MY_API_KEY
      bins:
        - curl
    primaryEnv: MY_API_KEY
    homepage: https://github.com/username/my-skill
---

# 技能说明文档

## 功能描述
...

## 使用方法
...
```

**⚠️ 关键：元数据必须准确声明**

ClawHub 安全分析会检查声明与实际代码是否一致：
- `requires.env` - 代码中引用的所有环境变量
- `requires.bins` - 代码中调用的所有 CLI 工具
- `primaryEnv` - 主要凭证变量名

#### package.json

```json
{
  "name": "my-skill",
  "version": "1.0.0",
  "description": "技能描述",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-skill.git"
  },
  "clawhub": {
    "requiresBinaries": ["curl"],
    "credentials": [
      {
        "name": "MY_API_KEY",
        "description": "API 密钥说明",
        "docs": "https://example.com/docs"
      }
    ]
  }
}
```

#### README.md

```markdown
# my-skill

简短介绍。

## 安装

```bash
clawhub install my-skill
```

## 配置

1. 获取凭证...
2. 配置环境变量...

## 使用

...
```

#### CHANGELOG.md

```markdown
# Changelog

## [1.0.0] - 2026-02-27

### 新增
- 初始版本
```

### 3. 推送到 GitHub

```bash
git add -A
git commit -m "Initial commit"
git remote add origin https://github.com/username/my-skill.git
git push -u origin main
```

### 4. 发布到 ClawHub

```bash
# 方式一：直接发布
clawhub publish . --slug my-skill --name "My Skill" --version 1.0.0 --changelog "初始版本"

# 方式二：使用 sync（推荐）
clawhub sync
```

### 5. 验证发布

```bash
# 检查技能信息
clawhub inspect my-skill

# 查看网页
open https://clawhub.ai/username/my-skill
```

## ⚠️ 常见问题与解决方案

### 问题 1: `fetch failed` 错误

**症状：**
```
✖ fetch failed
Error: fetch failed
```

**原因：** 网络问题、服务端暂时不可达或本机登录状态异常

**解决：**
```bash
# 检查网络连接
curl -I https://clawhub.ai

# 重新登录
clawhub login
clawhub whoami
```

### 问题 2: `SKILL.md required` 错误

**症状：**
```
Error: SKILL.md required
```

**原因：**
- 文件不存在
- 文件名大小写错误（必须是 `SKILL.md` 或 `skill.md`）
- 当前目录错误

**解决：**
```bash
ls -la SKILL.md
pwd
clawhub publish /absolute/path/to/skill --slug my-skill ...
```

### 问题 3: 发布超时（Timeout）

**症状：**
```
✖ Timeout
Error: Timeout
```

**原因：** 服务器响应慢或网络问题

**解决：**
```bash
# 检查服务器状态
curl -I https://clawhub.ai

# 重试发布
clawhub publish . --slug my-skill ...

# 或使用 sync
clawhub sync
```

### 问题 4: 元数据不一致（审核失败）

**症状：** 审核反馈 "metadata mismatch"

**原因：** SKILL.md frontmatter 声明与实际代码不符

**解决：** 确保 frontmatter 准确声明：

```yaml
---
name: my-skill
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - ACTUAL_ENV_VAR_USED_IN_CODE
      bins:
        - actual_binary_used_in_code
    primaryEnv: ACTUAL_ENV_VAR_USED_IN_CODE
    homepage: https://github.com/username/repo
---
```

### 问题 5: ClawHub 登录失败

**症状：**
```
- Verifying token
✖ fetch failed
```

**解决：**
```bash
# 重新登录
clawhub login
clawhub whoami

# 如仍失败，在受信任环境中人工检查本机 ClawHub 登录状态
```

### 问题 6: `gh release create` 或 `git push` 失败

**常见原因：**
- 没安装 `gh`
- GitHub CLI 未登录
- Git 没配置 `user.name` / `user.email`
- 仓库没配置 `origin`
- 当前账号对仓库无 push 权限

**排查顺序：**
```bash
which gh
gh auth status
git config --global --get user.name
git config --global --get user.email
git remote -v
```

**解决：**
```bash
# 安装 gh
brew install gh

# 登录 GitHub
gh auth login

# 配置 Git 身份
git config --global user.name "你的名字"
git config --global user.email "[email protected]"

# 补 remote
git remote add origin https://github.com/<user>/<repo>.git
```

## 📝 版本更新流程

```bash
# 1. 更新版本号
# 修改 SKILL.md frontmatter 中的 version
# 修改 package.json 中的 version

# 2. 更新 CHANGELOG.md
# 在顶部添加新版本记录

# 3. 提交并推送
git add -A
git commit -m "chore: bump version to 1.0.1"
git push

# 4. 先发 GitHub Release（必做）
gh release create v1.0.1 --title "v1.0.1" --notes "修复 xxx"

# 5. 再发布新版本到 ClawHub
clawhub publish . --slug my-skill --version 1.0.1 --changelog "修复 xxx"

# 或使用 sync（前提：GitHub Release 也要同步创建）
clawhub sync
```

## 🔐 安全注意事项

1. **凭证安全**
   - 不要在代码中硬编码密钥
   - 使用环境变量或 `mcporter config` 存储
   - 在 `.gitignore` 中排除敏感文件

2. **脚本审查**
   - 如果包含脚本文件，建议在文档中说明需要审查
   - 建议用户先在测试环境验证

3. **元数据准确性**
   - 准确声明所有依赖的环境变量和二进制文件
   - 这有助于安全分析和用户理解

## 📚 参考资源

- 技能格式规范：https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md
- 安全规范：https://github.com/openclaw/clawhub/blob/main/docs/security.md
- ClawHub 技能市场：https://clawhub.ai/skills

## 💡 最佳实践

1. **小步迭代** - 每次发布只做一个主要改动
2. **详细 Changelog** - 清晰记录每个版本的变更
3. **测试先行** - 在发布前充分测试技能功能
4. **文档完善** - 好的文档减少用户问题
5. **语义化版本** - 遵循 semver (major.minor.patch)

---

*最后更新：2026-02-27*
*作者：马锐拉 (@aliramw)*


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/clawhub-review-checklist.md

```markdown
# ClawHub 过审 Checklist

发布任何 OpenClaw 技能前，先逐项自查。目标不是“差不多”，而是**元数据、文档、实现三层完全一致**。

## 1. 元数据一致性

核对以下文件是否口径一致：

- `SKILL.md` frontmatter
- `package.json`
- `README.md`
- 实际脚本 / 代码

重点检查：

- `name`
- `description`
- `version`
- `homepage`
- `requires.bins`
- `requires.env`
- `primaryEnv`
- `clawhub.credentials`

## 2. 依赖声明

如果代码或文档里实际用到了这些东西，就必须声明：

- CLI 工具：如 `mcporter` / `git` / `gh` / `ffmpeg`
- 环境变量 / 凭证：如 `DINGTALK_MCP_DOCS_URL`
- 外部服务 URL / token

原则：**真实依赖了什么，就声明什么，不要少报。**

## 3. 凭证说明

如果 skill 需要 token / URL / key，必须写清：

- 凭证名字是什么
- 从哪获取
- 怎么配置
- 推荐存哪里
- 是否属于敏感信息

正文里最好明确：

- 推荐配置方式
- 备用配置方式
- 安全提醒

## 4. Instruction Scope 一致

文档里教用户做的事，不能超出代码真实边界。

重点排查：

- 文档是否让用户读 / 写某些本地文件
- 代码是否只允许 workspace 内路径
- 文档是否写了工作区外路径
- 文档是否暗示了代码并不支持的行为

原则：**文档、脚本、安全限制必须一致。**

## 5. 示例参数必须和真实实现一致

重点核对：

- 参数名大小写
- ID 格式
- URL 格式
- JSON 结构
- 返回值字段名

避免出现“README 看起来能用，复制后跑不通”。

## 6. 本地文件行为要明写

只要脚本会碰本地文件，就明确写清：

- 会读取什么文件
- 会输出什么文件
- 允许哪些扩展名
- 路径限制是什么
- 是否有限制大小
- 是否直接联网

## 7. 安装机制透明

如果需要外部工具：

- 写安装命令
- 写验证命令
- 不要偷偷依赖没声明的 CLI

## 8. 发布闭环

每次发布必须完整走完：

1. 更新版本号
2. 更新 `CHANGELOG.md`
3. `git add` / `commit`
4. `git push`
5. 创建 GitHub Release
6. 发布到 ClawHub
7. 同步到 `~/.openclaw/workspace/skills/<skill>/SKILL.md`

## 9. 测试最小集

至少覆盖：

- 路径安全
- 参数格式 / ID 格式
- 核心 happy path

如果改了安全逻辑，必须跑测试，不要只改文档。

## 10. 安全审查补充

重点新增这几类自查：

- description 不得包含机器本地目录路径（如 `~/Skills`、`~/.openclaw/workspace`）
- 不得推荐 TLS / 证书校验绕过命令（如 `NODE_TLS_REJECT_UNAUTHORIZED=0`）
- 不得把读取本地凭证文件内容作为常规排障步骤（如直接 `cat` token 文件）
- 对 agent 工作区或其他敏感目录的写操作，必须明确标注为受信任环境下的显式操作

## 11. 发版前最后一轮 grep

重点搜这些高风险词：

- `~/workspace`
- `~/Skills`
- `UUID v4`
- `NODE_TLS_REJECT_UNAUTHORIZED=0`
- `config.json`
- 旧版本号
- 未声明的 env 名
- 未声明的 CLI 名
- 旧参数名 / 旧接口名

## 三问自检

发版前最后问自己：

1. **我文档里写的，代码真能这么干吗？**
2. **我代码真实依赖的东西，元数据都声明了吗？**
3. **用户照 README 复制，真能跑通吗？**

只要其中一个答不上来，就先别发。

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# marila-skill-publish

马锐拉的 ClawHub 技能发布流程与经验总结，专门用于发布和更新 OpenClaw 技能到 ClawHub，并同步 GitHub Release。也覆盖 Git / GitHub CLI 安装、GitHub 鉴权、Git 初始化这些前置步骤。

## 📖 内容

本技能包含完整的 ClawHub 技能发布指南，基于实际发布 `dingtalk-ai-table` 技能的经验总结。

### 涵盖内容

- ✅ 完整的技能发布流程
- ✅ Git / GitHub CLI 安装说明
- ✅ GitHub 鉴权与 Git 初始化说明
- ✅ SKILL.md 元数据规范
- ✅ 常见问题与解决方案
- ✅ 版本更新流程
- ✅ 安全注意事项
- ✅ 最佳实践

## 🚀 使用

这是一个**文档技能**，主要用于参考和查阅。

```bash
# 安装技能
clawhub install marila-skill-publish

# 查看文档
cat ~/.openclaw/workspace/skills/marila-skill-publish/SKILL.md
```

## 📝 快速参考

### 发布命令

```bash
# 先发 GitHub Release（必做）
gh release create v1.0.0 --title "v1.0.0" --notes "更新说明"

# 再发布到 ClawHub
clawhub publish . --slug my-skill --version 1.0.0 --changelog "更新说明"

# 使用 sync 也一样：GitHub Release 不能省
clawhub sync
```

### 硬规则

- 发布任何 OpenClaw 技能时，**每次 ClawHub 发布都必须同步创建一个对应版本的 GitHub Release**
- 不允许只发技能、不发 release
- 发布前必须先检查 `references/clawhub-review-checklist.md`
- 如需同步到 agent 工作区，必须明确这属于敏感写操作，只在受信任环境执行

### 必需文件

- `SKILL.md` - 技能主文档（含 frontmatter 元数据）
- `package.json` - 包信息
- `README.md` - 使用说明
- `CHANGELOG.md` - 版本历史

### 关键元数据

```yaml
metadata:
  openclaw:
    requires:
      env: [YOUR_ENV_VAR]
      bins: [your-cli-tool]
    primaryEnv: YOUR_ENV_VAR
    homepage: https://github.com/user/repo
```

## 🔗 相关资源

- [ClawHub 过审 Checklist](references/clawhub-review-checklist.md)

- [ClawHub 技能市场](https://clawhub.ai/skills)
- [dingtalk-ai-table 技能](https://clawhub.ai/aliramw/dingtalk-ai-table)

---

**版本：** 1.0.0  
**作者：** 马锐拉 (@aliramw)  
**日期：** 2026-02-27

```

### _meta.json

```json
{
  "owner": "aliramw",
  "slug": "marila-skill-publish",
  "displayName": "marila-skill-publish",
  "latest": {
    "version": "1.0.7",
    "publishedAt": 1772839983571,
    "commit": "https://github.com/openclaw/skills/commit/24be2def35a0bc7e2111f6b057a6e8b82c61b7dc"
  },
  "history": [
    {
      "version": "1.0.2",
      "publishedAt": 1772658278765,
      "commit": "https://github.com/openclaw/skills/commit/e8e8763a3e97c4fcd758765d351fb8a4467a65eb"
    },
    {
      "version": "1.0.0",
      "publishedAt": 1772189849770,
      "commit": "https://github.com/openclaw/skills/commit/0577888fa5c8aa535727287314b217f3ddab35da"
    }
  ]
}

```