Openclaw的skill编写原则

Skill 编写规则

目录结构

skill-name/
├── SKILL.md              # 必须，唯一必要文件
├── scripts/              # 可选：可执行脚本（Python/Bash 等）
├── references/           # 可选：参考文档，按需加载到上下文
└── assets/               # 可选：输出用资源（模板、图片、字体等）

禁止创建 README.md、INSTALLATION_GUIDE.md、CHANGELOG.md 等辅助文档，只放 AI agent 执行任务所需的内容。

---

SKILL.md 结构

每个 SKILL.md 由两部分组成：

---
YAML frontmatter（必须）
---

Markdown 正文（必须）

---

YAML Frontmatter 字段

必须字段

字段	类型	说明
name	string	skill 唯一标识，小写字母+数字+连字符，≤64 字符
description	string	触发机制，决定 agent 何时使用此 skill

可选字段

字段	类型	说明
version	string	版本号，如 1.0.0
homepage	string	工具/服务的官方文档 URL
category	string	分类标签，如 content-creation
description_zh	string	中文描述（多语言支持）
license	string	许可证说明
user-invocable	boolean	true 表示可通过 /skill-name 命令直接调用
allowed-tools	string 或 array	限制 agent 可使用的工具，如 Bash(agent-browser:*) 或 ["message"]
metadata	object	OpenClaw 平台专用元数据（见下方详解）

---

metadata.openclaw 字段详解

metadata 是一个 JSON 对象，openclaw 键下包含平台集成信息：

metadata:
  {
    "openclaw": {
      "emoji": "🔐",
      "os": ["darwin", "linux"],
      "requires": { ... },
      "primaryEnv": "API_KEY_NAME",
      "install": [ ... ]
    }
  }

字段	类型	说明
emoji	string	skill 的展示图标
os	string[]	支持的操作系统："darwin"、"linux"、"win32"
requires	object	运行前置条件（见下方）
primaryEnv	string	主要的 API Key 环境变量名（用于 UI 配置入口）
install	array	安装步骤列表（见下方）

requires 对象

{
  "bins": ["op"],           // 必须存在的命令行工具（全部满足）
  "anyBins": ["claude", "codex"],  // 至少存在其中一个
  "env": ["NOTION_API_KEY"],       // 必须设置的环境变量
  "config": ["channels.discord.token"]  // 必须存在的配置路径
}

install 数组

每个安装步骤是一个对象，kind 决定类型：

// brew 安装
{
  "id": "brew",
  "kind": "brew",
  "formula": "gh",
  "bins": ["gh"],
  "label": "Install GitHub CLI (brew)"
}

// apt 安装
{
  "id": "apt",
  "kind": "apt",
  "package": "gh",
  "bins": ["gh"],
  "label": "Install GitHub CLI (apt)"
}

// npm 安装
{
  "id": "npm",
  "kind": "npm",
  "package": "@xdevplatform/xurl",
  "bins": ["xurl"],
  "label": "Install xurl (npm)"
}

// node 安装（等同 npm global）
{
  "id": "node-claude",
  "kind": "node",
  "package": "@anthropic-ai/claude-code",
  "bins": ["claude"],
  "label": "Install Claude Code CLI (npm)"
}

// go install
{
  "id": "go",
  "kind": "go",
  "module": "github.com/steipete/sonoscli/cmd/sonos@latest",
  "bins": ["sonos"],
  "label": "Install sonoscli (go)"
}

// pip 安装
{
  "id": "pip-pdf-libs",
  "kind": "command",
  "command": "pip3 install pypdf pdfplumber reportlab",
  "label": "Install core PDF libraries"
}

// 文件下载（带 os 过滤）
{
  "id": "download-runtime-macos",
  "kind": "download",
  "os": ["darwin"],
  "url": "https://...",
  "archive": "tar.bz2",
  "extract": true,
  "stripComponents": 1,
  "targetDir": "runtime",
  "label": "Download sherpa-onnx runtime (macOS)"
}

---

description 字段的写法

description 是 skill 最重要的字段，是 agent 决定是否触发 skill 的唯一依据（正文在触发后才加载）。

好的 description 包含：

• 是什么：skill 的功能
• 何时用：明确的触发场景，可以用 Use when: 列举
• 何时不用：NOT for: 排除不适用场景（避免误触发）
• 触发词：用户可能说的具体短语

# 好的例子
description: "GitHub operations via `gh` CLI: issues, PRs, CI runs, code review, API queries. Use when: (1) checking PR status or CI, (2) creating/commenting on issues. NOT for: complex web UI interactions, bulk operations across many repos."

# 也可以包含命令用法（user-invocable skill）
description: "Fetch GitHub issues, spawn sub-agents to implement fixes and open PRs. Usage: /gh-issues [owner/repo] [--label bug] [--limit 5]"

---

正文（Markdown Body）的写法原则

1. 简洁优先：上下文窗口是公共资源，每段内容都要问”agent 真的需要这个吗？”
2. 正文 ≤ 500 行：超出时拆分到 references/ 文件，并在正文中明确引用
3. 渐进式披露：正文只放核心工作流，细节放 references，按需加载
4. 不放”何时使用”章节：触发判断在 description 里，正文在触发后才读
5. 用命令式/不定式：写指令而非描述，如”Run X”而非”You should run X”
6. 代码示例优于文字解释：具体命令比段落更有效

references 文件的引用方式：

## Advanced features
- **Form filling**: See [references/forms.md](references/forms.md) for complete guide
- **API reference**: See [references/api.md](references/api.md)

---

命名规范

• 全小写，只用字母、数字、连字符
• 长度 ≤ 64 字符
• 优先动词短语：gh-issues、skill-creator、video-frames
• 工具相关时加命名空间：openai-whisper、openai-whisper-api
• 目录名与 name 字段完全一致

最佳实践

可以直接使用一些skill creator的skill来辅助用户创建，比如：

• Skill Creator
• Skill Creator