OpenClaw Skill 编写教程

📝 OpenClaw Skill 编写教程

一、什么是 Skill

Skill 是 OpenClaw 的可触发工作流单元。你可以把它理解为一个”技能包”——当用户的请求匹配到某个 Skill 的触发描述时，对应的 SKILL.md 就会被加载，提供该领域的专属指导。
与系统 Prompt 不同，Skill 是按需加载的，文件存在时才触发，不会污染基础上下文。

二、Skill 的目录结构

一个 Skill 就是一个文件夹，结构如下：

skill-name/
  SKILL.md          ← 核心文件，**必须**
  scripts/           ← 可选，自动化脚本
  references/       ← 可选，长文档/参考资料
  assets/           ← 可选，模板/媒体文件
  agents/           ← 可选（很少用）

最简情况下，只需一个 SKILL.md。

三、SKILL.md 的格式

SKILL.md 由两部分组成：YAML frontmatter + 正文。

3.1 Frontmatter（必需）

---
name: my-skill          # 唯一标识，文件夹名即是，不强制要求重复
description: "一句话描述，什么时候触发这个 Skill"
---

description 是触发关键词，决定何时加载这个 Skill。描述要精准、简短，避免通用废话。
可选额外字段：
字段说明
homepag 文档链接
allowed-tool 限制可用工具列表
user-invocabl 是否可被用户手动触发
metadat 自定义元数据
licens 许可证

3.2 正文（推荐写法）

# My Skill

简短说明这个 Skill 的用途。

## Workflow

1. 步骤一
2. 步骤二

## 注意事项

- 注意点A
- 注意点B

正文风格建议：

• 用 fragment（短句） 而非完整句子，越简洁越好
• 只写”模型容易忽略/搞错的”内容，不要重复常识
• 不要写冗长的 README，Codex/LLM 本身就很强

四、实战：写一个”PDF处理” Skill

假设你想写一个 PDF 处理的 Skill：

Step 1：创建文件夹

mkdir -p ~/my-skills/pdf-tools

Step 2：写 SKILL.md

---
name: pdf-tools
description: "Inspect, split, merge, OCR, redact, or convert PDFs with local CLI tools."
---

# PDF tools

Use for PDF manipulation. Prefer deterministic scripts for page edits.

## Workflow

1. Inspect file → `pdfinfo <file>` or `ls -la`
2. Choose operation:
   - **Split**: `pdftk <file> burst`
   - **Merge**: `pdftk <file1> <file2> cat output <out>`
   - **Extract pages**: `pdftk <file> cat <pages> output <out>`
   - **OCR**: `tesseract <image> <output> -l <lang>`
3. Write output **beside input** unless user asked otherwise.
4. Verify with `pdfinfo <output>`.

这就是一个完整可用的 Skill。

五、让你的 Skill 被 OpenClaw 发现

有两种方式：

方式 A：放到插件目录（推荐）

~/.openclaw/plugin-skills/my-skill/SKILL.md

这样 OpenClaw 会自动扫描并加载。

方式 B：注册到系统 Skills 目录

放在 /usr/lib/node_modules/openclaw/skills/ 下（需要有管理员权限）。

六、引用外部脚本

如果你的 Skill 需要运行特定脚本，放到 scripts/ 目录下：

pdf-tools/
  SKILL.md
  scripts/
    split_pdf.sh
    merge_pdf.sh

在 SKILL.md 中直接调用：

bash ~/.openclaw/plugin-skills/pdf-tools/scripts/split_pdf.sh <args>

七、长文档放到 references/

如果参考资料很长，不要塞进 SKILL.md，放到 references/ 下，需要时再读取。

pdf-tools/
  SKILL.md
  references/
    pdf-lib-manual.md    # 仅在需要时读取

八、验证你的 Skill

写完后可以用这个脚本验证 frontmatter：

python skills/skill-creator/scripts/quick_validate.py ~/.openclaw/plugin-skills/my-skill

或手动检查：

python - <<'PY'
from pathlib import Path
import yaml

path = Path("~/.openclaw/plugin-skills/my-skill/SKILL.md").expanduser()
text = path.read_text()

if not text.startswith("---\n"):
    raise SystemExit("❌ 缺少 frontmatter")

fm = text.split("---", 2)[1]
yaml.safe_load(fm)
print("✅ Frontmatter 格式正确")
PY

九、好 Skill 的设计原则

✅ 建议 ❌ 避免
description 精准匹配触发词 description 写得太泛
正文简洁，只写模型容易错的地方写完整教程/文档
包含具体命令/参数示例空话套话
scripts 用确定性脚本依赖复杂环境
引用长文档到 references/ 全部塞进 SKILL.md

十、示例：查看现有 Skill 找感觉

已有的 Skill 都放在这里，可以直接参考写法：

ls /usr/lib/node_modules/openclaw/skills/
ls ~/.openclaw/plugin-skills/