skill-creator-plus

# skill-creator-plus

创建符合 ClawHub 规范的 OpenClaw 技能。按以下规则执行，不要跳过章节，不要发明规范中未列出的约定。

未提供技能名和用途时，先询问用户。

---

## 关于 Skills

Skills 是模块化、自包含的包，通过提供专业化的工作流程、工具和知识来扩展 OpenClaw 的能力。可以把 Skill 看作特定领域或任务的"入职指南"——它们将 OpenClaw 从通用 agent 转变为具备专门处理流程的 specialized agent，而这是任何模型都无法完全拥有的能力。

### Skills 能提供什么

1. **专业化工作流程** — 特定领域的多步骤流程
2. **工具集成** — 操作特定文件格式或 API 的指引
3. **领域专业知识** — 公司专属知识、Schema、业务逻辑
4. **打包资源** — 复杂重复任务的脚本、参考资料和资产文件

---

## 核心原则

### 简洁是关键

context window 是公共资源。Skills 与 OpenClaw 所需的其他内容共享 context window：system prompt、对话历史、其他 Skills 的元数据，以及实际的用户请求。

**默认假设：OpenClaw 已经非常聪明。** 只添加 OpenClaw 还没有的内容。每一条信息都要质疑："OpenClaw 真的需要这个解释吗？"以及"这个段落的 token 消耗值得吗？"

用简洁的例子替代冗长的解释。

### 设定适当的自由度

根据任务的脆弱性和可变性匹配具体的约束程度：

**高自由度（基于文本的指令）**：当多种方法都可行、决策依赖上下文或启发式方法引导方案时使用。

**中自由度（伪代码或带参数的脚本）**：当存在优选模式、可接受一定变化或配置影响行为时使用。

**低自由度（特定脚本，参数少）**：当操作脆弱易错、一致性至关重要或必须遵循特定顺序时使用。

可以把 OpenClaw 想象成在探索一条路径：狭窄的悬崖桥需要具体的护栏（低自由度），而开阔的场地允许多条路线（高自由度）。

---

## 文件结构

只生成两个文件——无 README.md、无 CHANGELOG.md、无辅助文档：

```
[skill-name]/
├── SKILL.md       (required)
└── _meta.json     (required)
```

### 技能的结构

每个技能由一个必需的 SKILL.md 文件和可选的打包资源组成：

```
skill-name/
├── SKILL.md（必需）
│   ├── YAML frontmatter 元数据（必需）
│   │   ├── name:（必需）
│   │   └── description:（必需）
│   └── Markdown 说明（必需）
└── 打包资源（可选）
    ├── scripts/      - 可执行代码（Python/Bash 等）
    ├── references/   - 文档，按需加载到 context 中
    └── assets/       - 输出中使用的文件（模板、图标、字体等）
```

#### SKILL.md（必需）

每个 SKILL.md 包含：

- **Frontmatter**（YAML）：包含 `name` 和 `description` 字段。这是 OpenClaw 判断技能何时被使用的唯一依据。
- **Body**（Markdown）：技能使用说明。**仅在技能触发后加载**（如果需要的话）。

#### 打包资源（可选）

**Scripts（`scripts/`）**：可执行代码，用于需要确定性可靠性或被反复重写的任务。优势：token 高效、确定性、可不加载到 context 中执行。

**References（`references/`）**：文档和参考资料，按需加载。优势：保持 SKILL.md 精简，仅在 OpenClaw 判定需要时加载。

**Assets（`assets/`）**：不打算加载到 context 中的文件，而是用于 OpenClaw 生成的输出中（模板、图片、样板代码等）。

#### 什么不应该包含

技能应只包含直接支持其功能的必要文件。**不要**创建：README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md 等。

---

## 渐进式披露设计原则

Skills 使用三级加载系统来高效管理 context：

1. **元数据（name + description）** — 始终在 context 中（约100词）
2. **SKILL.md 正文** — 技能触发时（<5000词）
3. **打包资源** — OpenClaw 按需加载（无限量）

保持 SKILL.md 正文简洁且在500行以内以减少 context 膨胀。内容接近此限制时分拆到单独文件。

**核心原则**：当技能支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流和选择指引。将变体特有细节移到单独的 reference 文件。

---

## 理解 ClawHub Scanner

在写任何内容之前，先理解 scanner 的工作方式：

**1. description 摘要是 scanner 唯一信任的信息。**
`_meta.json` 字段（`requiredConfigPaths`、`primaryCredential`、`requires`）被存储但**不会**在 registry API 中显示。scanner 需要验证的一切必须在 description 中——而且是**前 ~160 字符内**（registry 截断点）。

**2. scanner 是迭代的——每次修复暴露下一个问题。**
每个 rejected 版本都计入技能历史。在 checklist 通过之前不要发布。

**3. scanner 无法验证嵌套内容。**
嵌入在 here-string 或其他代码块内的脚本会被标记为截断和无法验证。所有 scanner 需要读取的内容必须是扁平的、独立的。

**4. scanner 是语义化的，不是关键词匹配。**
它理解 logged vs transmitted、always:true vs always:false、handle vs userId、required vs optional credentials 的区别。

**5. scanner 默认保守。**
它阻止和警告而不是批准。

---

## OpenClaw Parser Gotchas（导致技能静默消失）

这些会静默破坏技能检测——无报错，技能直接从 `openclaw skills list` 消失：

- **Frontmatter 缺少闭合 `---`**：OpenClaw 会完全静默解析失败。始终验证闭合分隔符存在。
- **`openclaw` 在 `metadata.openclaw.requires.bins` 中**：OpenClaw 不识别自身为要检查的 bin，会静默隐藏技能。永远不要把 openclaw 放入 bins。
- **`~/.openclaw/skills/` 中的技能默认自动加载**：`managedSkillsDir = ~/.openclaw/skills/` 是 OpenClaw 默认始终加载的路径，无需 extraDirs 配置。
- `extraDirs` 仅用于加载非标准路径的技能（如 `~/.config/my-skills/`）。
- **编码**：始终用 UTF-8 no-BOM 编码写入 SKILL.md。BOM 会静默破坏 YAML 解析。

---

## ClawHub Scanner Criteria

逐项明确处理——先在 description 中处理，再在正文中处理。

### 1. Purpose & Capability
- 精确说明调用哪些 API/服务（如 "feishu.open.feishu.cn only"）
- 说明技能**不**做什么（如 "no data forwarded to third parties"）
- 后台进程：精确说明什么是 READ、什么是 TRANSMITTED、什么是 LOGGED
- 长生命周期 token：说明 rotation 指引 + 主机入侵时立即 rotation
- 一次性 setup secrets：明确说明"delete afterward"

### 2. Instruction Scope
- Required binaries 和 credentials 在 description 开头（fits in ~160-char summary）
- Required CLIs 在**两处**都声明：
  - `metadata.openclaw.requires.anyBins`（SKILL.md frontmatter）
  - `_meta.json requires.anyBinaries`（registry 元数据）
- SKILL.md 正文和 _meta.json 必须一致
- OS 限制在 description 中说明
- 最小权限：声明 "grant token minimal permissions only"

### 3. Install Mechanism
- 运行时无外部脚本下载——所有 worker 代码内联在 SKILL.md 中
- Worker 脚本从 SKILL.md 运行时提取，不是从字符串字面值构造

### 4. Credentials
- 所有 credential 要求在 description 中命名（文件路径 + 字段名）
- 区分 required vs optional 字段
- 任何脚本中无 token 字面值——运行时从磁盘读取
- 所有运行时文件权限限制（icacls/chmod 600）
- 长期 token：包含 rotation 指引和入侵时立即 rotation 说明

### 5. Persistence & Privilege
- `always:true` 在社区技能中禁止
- 后台进程仅 opt-in——永不自主启动
- 在 _meta.json 中声明 persistence
- Description 必须说明：什么被 READ、被 TRANSMITTED、被 LOGGED，去向

---

## 技能创建流程

技能创建包含以下步骤：

1. 用具体示例理解技能
2. 规划可复用的技能内容（scripts、references、assets）
3. 初始化技能（运行 init_skill.py，如需要）
4. 编辑技能（实现资源并编写 SKILL.md）
5. 打包技能（运行 package_skill.py，如需要）
6. 基于实际使用迭代

### Step 1：用具体示例理解技能

只有当技能的用法已经充分理解时才跳过此步。即使在处理现有技能时，这一步仍然有价值。

要创建一个有效的技能，需要清晰理解技能使用的具体示例。例如，构建 image-editor 技能时：
- "image-editor 技能应该支持什么功能？编辑、旋转、还是其他？"
- "能给一些技能使用方式的示例吗？"

从最重要的问题开始，当对技能应支持的功能有了清晰认识时结束此步。

### Step 2：规划可复用的技能内容

将具体示例转化为有效技能：
1. 考虑如何从零开始执行这个示例
2. 确定执行这些工作流时，哪些 scripts、references 和 assets 会很有帮助

### Step 3：初始化技能

从零创建新技能时，运行 `init_skill.py` 脚本：

```bash
python3 scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets]
```

### Step 4：编辑技能

编辑技能时，记住技能是为另一个 OpenClaw 实例创建的。包括对另一个 OpenClaw 实例执行这些任务有益且非显而易见的 info。

### Step 5：打包技能

技能开发完成后，打包成分发的 .skill 文件：

```bash
python3 scripts/package_skill.py <path/to/skill-folder>
```

打包脚本会自动验证 YAML frontmatter、命名规范、description 质量、文件组织。

### Step 6：迭代

测试技能后，用户可能会要求改进：
1. 用技能处理真实任务
2. 注意到困难或低效之处
3. 确定 SKILL.md 或打包资源应如何更新
4. 实现更改并再次测试

---

## 文件格式规范

### SKILL.md Frontmatter

```yaml
---
name: [skill-name]
description: "[一句话描述技能做什么 — 动作导向，不以'AI'开头]. Requires: [binaries]. Reads [credentials file] ([FIELDS]). [Setup-only secrets: delete afterward.] [Long-lived tokens: rotate periodically; rotate immediately if host compromised.] Grant token minimal permissions only. No data forwarded to third parties; all calls go to [domain] only."
metadata: {"openclaw":{"emoji":"[icon]","requires":{"anyBins":[]}}}
---
```

**规则**：
- Description 是一个**带引号的单行字符串**
- **首先写亮点说明**——用清晰、动作导向语言（如 "Facebook Page manager: post, schedule, reply & get insights"）。这是用户在 ClawHub 搜索时首先读到的。**不要**以"AI"开头。**不要**以"Requires:"开头。
- 技术要求跟在亮点说明后面
- 亮点说明 + 技术要求合并后在 ~160 字符内
- **永远不要**把 openclaw 放入 bins 或 anyBins
- **不要**使用 always:true
- **不要**添加其他 frontmatter 字段
- Frontmatter **必须**以闭合的 `---` 行结束

**好的 description 示例**：
```
"Facebook Page manager: post, schedule, reply & get insights. Requires: powershell/pwsh. Reads ~/.config/fb-page/credentials.json (FB_PAGE_TOKEN, FB_PAGE_ID). FB_APP_SECRET for one-time setup only — delete afterward. Long-lived token; rotate periodically and immediately if host is compromised. Grant minimal permissions only. No data forwarded to third parties; all calls go to graph.facebook.com only."
```

### _meta.json

```json
{
  "ownerId": "[registry-userId-not-handle]",
  "slug": "[skill-name]",
  "version": "1.0.0",
  "publishedAt": "YYYY-MM-DDTHH:MM:SSZ",
  "requiredEnvVars": [],
  "requiredConfigPaths": [],
  "primaryCredential": null,
  "persistence": null,
  "credentialSetup": {
    "type": "none",
    "description": "No credentials required."
  },
  "requires": {
    "anyBinaries": [],
    "os": ["windows", "macos", "linux"]
  }
}
```

**关键规则**：
- `ownerId` 必须是 registry userId，**不是** handle（从 `clawhub inspect <slug> --json` 输出中获取 `owner.userId`）
- 如果有凭证：`_meta.json` 需要 `requiredConfigPaths`、`primaryCredential`
- 如果有后台进程：`_meta.json` 需要 `persistence` 块
- **永远不要**在 `requires.binaries` 中包含 `openclaw`

---

## SKILL.md 内容结构

### STEP 1 — 凭证加载（如需要）

如果缺失，显示完整 setup 流程：
1. 检测可用资源
2. 要求用户提供所需值
3. 保存配置文件
4. 立即限制所有运行时文件权限

### STEP 2 — 核心功能

- 支持操作表（方法、端点、参数）
- 每种请求类型的可复用调用模式
- 所有代码内联——无外部脚本下载
- 所有 API 调用包装在 try/catch 中

### STEP 3 — 错误处理

- 每个 API 调用的 try/catch
- 错误代码表，包含精确修复方法
- 告诉用户每个错误具体要做什么

### Agent Rules（始终包含）

- 先加载凭证；如缺失，引导 setup
- 永不将 tokens 作为字面值嵌入——运行时从磁盘读取
- 立即限制所有运行时文件的权限
- 日志只含 metadata——无 secrets，无 message 内容
- 后台进程 opt-in——无明确用户请求不启动
- 任何错误：解析错误代码，对照表格，告诉用户具体要做什么
- 对于 setup-only secrets：提醒用户使用后删除
- 对于长期 tokens：提醒定期 rotation，主机入侵时立即 rotation

---

## 发布后

```bash
# 设置 GitHub repo About 和 homepage（每次 push 后运行）
gh repo edit [owner]/[skill-name] \
  --description "OpenClaw skill: [one-line purpose]" \
  --homepage "https://clawhub.ai/[owner]/[skill-name]"
```

---

## 安全规则（不可协商）

- 永不硬编码用户 ID、channel ID、tokens 或个人标识符
- 所有 secrets 在用户拥有的配置文件中
- Worker 运行时从磁盘读取凭证
- icacls/chmod 600 on ALL 运行时文件
- 日志：仅 metadata——无 secrets，无 message 内容
- 长期 tokens：rotation 指引；入侵时立即 rotation
- Setup-only secrets：使用后删除说明
- 后台进程 opt-in 且在 _meta.json 中声明
- always:true 禁止
- ownerId 必须是 registry userId
- 最小权限：明确声明 "grant token minimal permissions only"

---

## Validation Checklist（发布到 ClawHub 之前必须逐项确认）

### DESCRIPTION / SUMMARY（scanner 只读 ~160 字符）
- [ ] 用清晰明了的亮点说明开头（做什么，动作导向，不以"AI"开头）
- [ ] 亮点说明后面跟着："Requires: [binaries]. Reads [credentials file] ([fields])."
- [ ] 亮点说明 + 技术要求合并在 ~160 字符内
- [ ] 前 ~160 字符内包含必需 binaries
- [ ] 前 ~160 字符内包含凭证文件路径和字段名
- [ ] 明确命名 API/服务
- [ ] 声明 "No data forwarded to third parties; all calls go to [domain] only"
- [ ] 后台进程：TRANSMITTED / LOGGED 分解在 description 中
- [ ] Setup-only secrets：声明 "delete afterward"
- [ ] Long-lived tokens：声明 rotation + 入侵时立即 rotation
- [ ] 最小权限：声明 "grant token minimal permissions only"

### FRONTMATTER（parser gotchas——静默失败）
- [ ] frontmatter 块必须以 `---` 正确闭合（不能缺少结尾分隔符）
- [ ] 只有 name 和 description（加 metadata 行）——无其他 frontmatter 字段
- [ ] `metadata.openclaw.requires` 使用 `anyBins`——**不是** `bins: ["openclaw"]`
- [ ] 任何地方都没有 openclaw 在 bins 或 anyBins 中
- [ ] 无 always:true
- [ ] 文件以 UTF-8 no-BOM 编码写入

### _meta.json
- [ ] ownerId 是 registry userId（不是 handle）
- [ ] requiredConfigPaths 列出所有凭证文件
- [ ] primaryCredential.fields 列出所有字段；required/optional 分离
- [ ] 有后台进程时有 persistence 块
- [ ] requires.anyBinaries 已声明（不是 binaries: ["openclaw"]）

### 一般规则
- [ ] 无 README.md 或辅助文档
- [ ] 无硬编码个人 ID、tokens、channel 名称
- [ ] 发布前 `openclaw skills list` 确认技能为 ✓ ready

### 发布后
- [ ] GitHub repo About description 已设置
- [ ] GitHub repo homepage 已设置为 ClawHub URL
- [ ] `openclaw skills list` 确认技能为 ready
- [ ] `clawhub inspect [slug]` summary 以亮点说明开头

---

## 常见错误案例

### 错误1：description 以技术要求开头
```
"Requires: powershell/pwsh. Reads ~/.config/fb-page/credentials.json..."
```
用户在 ClawHub 搜索时跳过干巴巴的技术信息——他们先看亮点说明。

### 错误2：版本号不一致
SKILL.md frontmatter、_meta.json、ClawHub 三端版本必须完全一致。

### 错误3：scripts 文件名不匹配
SKILL.md 中写的脚本文件名必须与实际文件名完全一致。

### 错误4：缺少 frontmatter 闭合 `---`
OpenClaw 完全静默解析失败，技能从列表消失。

### 错误5：把 openclaw 放入 anyBins
openclaw runtime 永远不满足自己，技能被静默隐藏。

---

## 发布命令

```bash
clawhub publish <path/to/skill-folder> --slug <slug-name> --version <version>
```

版本号规则（semver）：
- 首次发布：1.0.0
- 小改（错别字、描述优化）：patch +0.0.1
- 功能增加/改进：minor +0.1.0
- 破坏性变更：major +1.0.0