marila-skill-publish

# 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 "you@example.com"
```

如果仓库还没绑远程：

```bash
git remote add origin https://github.com/<user>/<repo>.git
# 或
# git remote add origin git@github.com:<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**。不允许只发技...

# 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