OpenClaw Skill 开发从零开始配置教程
OpenClaw Skill 开发从零开始配置教程
实验目标
本教程主要讲解如何在 OpenClaw 中创建自定义 Skill，从基础概念到完整实践，完成一个 WordPress 文章发布 Skill 的系统搭建。
实验内容
- 了解 Skill 的本质和设计原则
- 掌握 Skill 的标准结构
- 使用 init_skill.py 初始化技能
- 编写 SKILL.md 和脚本工具
- 打包和分发技能
简介
根据 OpenClaw 的设计理念，Skill 是「特定领域的入职指南」—— 把通用 AI 变成专家。通过 Skill，你可以让 AI 掌握专业工作流、工具集成和领域知识。
Skill 开发方式对比
| 方式 | 优点 | 缺点 |
|---|---|---|
| 直接修改内置 Skill | 立即可用，无需配置 | 更新时会被覆盖，不推荐 |
| 在 workspace 创建 Skill | 安全，可版本控制，推荐 | 需要手动加载 |
| 打包成 .skill 文件 | 便于分发和分享 | 需要解压安装 |
我们在综合考虑了安全性、可维护性、可分享性等方面后，选择了在 workspace 创建 Skill + 打包分发作为开发方式。
Skill 是什么
Skill 是模块化、自包含的包，通过提供专业化知识、工作流和工具来扩展 AI 的能力。可以把它们想象成「特定领域的入职指南」—— 将通用 AI 转变为具备专业程序性知识的专家。
Skill 提供什么
- 专业化工作流 – 特定领域的多步骤流程
- 工具集成 – 操作特定文件格式或 API 的说明
- 领域知识 – 公司特定知识、Schema、业务逻辑
- 捆绑资源 – 脚本、参考文档和复杂任务的资产
核心设计原则
简洁至上
上下文窗口是公共资源。Skill 与 AI 需要的所有其他内容共享上下文窗口：系统提示、对话历史、其他 Skill 的元数据，以及实际的用户请求。
默认假设：AI 已经很聪明了。 只添加 AI 还不知道的上下文。挑战每一条信息：”AI 真的需要这个解释吗？”和”这段内容值得它的 token 成本吗？”
优先使用简洁的示例，而不是冗长的解释。
自由度匹配
根据任务的脆弱性和可变性匹配合适的 specificity 级别：
高自由度（文字指导）：当多种方法都有效、决策依赖上下文或启发式方法指导时使用。
中自由度（伪代码或带参数的脚本）：当存在推荐模式、可接受一定变化或配置影响行为时使用。
低自由度（具体脚本，少量参数）：当操作脆弱易错、一致性至关重要或必须遵循特定顺序时使用。
把 AI 想象成在探索一条路：狭窄的桥（有悬崖）需要具体的护栏（低自由度），而开阔的田野允许多条路线（高自由度）。
渐进式披露设计
Skill 使用三级加载系统来高效管理上下文：
- 元数据（name + description） – 始终在上下文中（约 100 词）
- SKILL.md 正文 – Skill 触发后加载（<5k 词）
- 捆绑资源 – AI 按需读取（无限制）
手动逐步创建 Skill
安装条件
查看 OpenClaw 版本
openclaw --version确认 workspace 位置
# 默认 workspace 位置
~/.openclaw/workspace/skills/创建步骤
本教程讲解在 OpenClaw 中创建 Skill 的完整步骤。
初始化 Skill
使用 init_skill.py 脚本可以快速生成 Skill 模板：
python3 /opt/openclaw/skills/skill-creator/scripts/init_skill.py \
<skill-name> \
--path <output-directory> \
[--resources scripts,references,assets] \
[--examples]示例：
# 创建基础 Skill
python3 /opt/openclaw/skills/skill-creator/scripts/init_skill.py \
my-skill \
--path ~/.openclaw/workspace/skills
# 创建带资源目录的 Skill
python3 /opt/openclaw/skills/skill-creator/scripts/init_skill.py \
sys-info \
--path ~/.openclaw/workspace/skills \
--resources scripts,references
# 创建带示例文件的 Skill
python3 /opt/openclaw/skill-creator/scripts/init_skill.py \
my-skill \
--path ~/.openclaw/workspace/skills \
--resources scripts \
--examples该脚本会：
- 在指定路径创建 Skill 目录
- 生成带有正确 frontmatter 和 TODO 占位符的 SKILL.md 模板
- 根据
--resources参数创建资源目录 - 如果设置了
--examples，添加示例文件
Skill 结构
每个 Skill 由必需的 SKILL.md 文件和可选的捆绑资源组成：
skill-name/
├── SKILL.md (必需)
│ ├── YAML frontmatter metadata (必需)
│ │ ├── name: (必需)
│ │ └── description: (必需)
│ └── Markdown instructions (必需)
└── Bundled Resources (可选)
├── scripts/ - 可执行代码（Python/Bash 等）
├── references/ - 文档参考
└── assets/ - 输出中使用的文件（模板、图标等）SKILL.md（必需）
每个 SKILL.md 包含：
- Frontmatter（YAML）：包含
name和description字段。这是 AI 判断何时使用 Skill 的唯一依据，因此清晰全面地描述 Skill 是什么以及何时使用它非常重要。 - 正文（Markdown）：使用 Skill 的说明和指导。仅在 Skill 触发后加载。
Frontmatter 示例
---
name: wordpress-publish
description: "WordPress 文章发布和管理技能。通过 wp-cli 或 REST API 发布文章、管理分类、上传媒体。当用户需要发布博客文章、更新内容、管理 WordPress 站点时使用。不适用于：复杂页面布局设计、主题开发、插件开发。"
metadata:
{
"openclaw":
{
"emoji": "📝",
"requires": { "bins": ["wp", "curl"] },
"install":
[
{
"id": "brew",
"kind": "brew",
"formula": "wp-cli",
"bins": ["wp"],
"label": "Install WP-CLI (brew)",
},
{
"id": "apt",
"kind": "apt",
"package": "wp-cli",
"bins": ["wp"],
"label": "Install WP-CLI (apt)",
},
],
}
}
---正文结构
# Skill 名称
## 何时使用
✅ **使用此技能的情况：**
- 使用场景 1
- 使用场景 2
- 使用场景 3
## 何时不使用
❌ **不要使用此技能的情况：**
- 不适用场景 1 → 使用 X 替代
- 不适用场景 2 → 使用 Y 替代
## 设置
```bash
# 一次性配置命令常用命令
分类 1
# 命令示例 1
command arg1 arg2
# 命令示例 2
command --flag value分类 2
# 命令示例模板
模板 1
#!/bin/bash
# 可复用脚本模板注意事项
- 重要提示 1
- 重要提示 2
相关资源
- 详细命令参考: 见
references/commands.md - API 参考: 见
references/api.md
捆绑资源（可选）
scripts/
用于需要确定性可靠性或重复编写相同代码的任务的可执行代码（Python/Bash 等）。
- 何时包含：当重复编写相同代码或需要确定性可靠性时
- 示例：
scripts/rotate_pdf.py用于 PDF 旋转任务 - 好处：Token 高效、确定性、可在不加载到上下文的情况下执行
references/
用于加载到上下文中以告知 AI 流程和思维的文档和参考材料。
- 何时包含：用于 AI 工作时需要参考的文档
- 示例：
references/finance.md用于财务 Schema，references/api_docs.md用于 API 规范 - 用例：数据库 Schema、API 文档、领域知识、公司政策、详细工作流指南
- 好处：保持 SKILL.md 精简，仅在 AI 确定需要时加载
assets/
不打算加载到上下文中，而是在 AI 生成的输出中使用的文件。
- 何时包含：当 Skill 需要在最终输出中使用的文件时
- 示例：
assets/logo.png用于品牌资产，assets/slides.pptx用于 PowerPoint 模板 - 用例：模板、图像、图标、样板代码、字体、示例文档
打包 Skill
Skill 开发完成后，需要打包成可分发的 .skill 文件：
# 方法 1：使用 package_skill.py（推荐）
python3 /opt/openclaw/skills/skill-creator/scripts/package_skill.py \
~/.openclaw/workspace/skills/my-skill
# 方法 2：手动打包（zip 格式）
cd ~/.openclaw/workspace/skills
zip -r my-skill.skill my-skill/ -x "*.git*" "*.pyc" "__pycache__/*"打包脚本会：
-
自动验证 Skill，检查：
- YAML frontmatter 格式和必需字段
- Skill 命名约定和目录结构
- 描述完整性和质量
- 文件组织和资源引用
-
打包 Skill（如果验证通过），创建名为
my-skill.skill的 .skill 文件
.skill 文件格式：带 .skill 扩展名的 zip 文件
安全限制：符号链接会被拒绝，打包失败
如何使用 Skill
安装 Skill
# 方法 1：复制到 workspace
cp -r my-skill ~/.openclaw/workspace/skills/
# 方法 2：解压 .skill 文件
unzip my-skill.skill -d ~/.openclaw/workspace/skills/使用 Skill
Skill 安装后，OpenClaw 会自动加载。直接向 AI 提问即可触发 Skill：
用户："发布一篇 WordPress 文章"
AI：[自动匹配 wordpress-publish Skill]
AI："我来帮你发布文章。请提供：
1. 文章标题
2. 文章内容
3. 分类和标签"Skill 开发最佳实践
命名规范
- 仅使用小写字母、数字和连字符
- 将用户提供的标题规范化为连字符格式（例如：”Plan Mode” →
plan-mode） - 生成不超过 64 个字符的名称
- 优先使用简短的动词引导短语
- 按工具命名以提高清晰度（例如：
gh-address-comments、linear-address-issue） - Skill 文件夹名称与 Skill 名称完全一致
编写指南
Frontmatter
name：Skill 名称description：这是 Skill 的主要触发机制，帮助 AI 理解何时使用 Skill- 包含 Skill 做什么以及何时使用的具体触发器/上下文
- 将所有”何时使用”信息放在这里——而不是正文中
- 示例：
description: "全面的文档创建、编辑和分析，支持修订模式、评论、格式保留和文本提取。当需要处理专业文档 (.docx 文件) 时用于：(1) 创建新文档，(2) 修改内容，(3) 处理修订模式，(4) 添加评论"
正文
- 始终使用命令式/不定式形式
- 保持简洁（<500 行）
- 使用表格和代码块提高可读性
- 包含具体示例
不要包含的内容
Skill 只应包含直接支持其功能的基本文件。不要创建额外的文档或辅助文件，包括：
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- 等
Skill 只应包含 AI 执行工作所需的信息。它不应包含关于创建过程的辅助上下文、设置和测试程序、面向用户的文档等。
迭代优化
Skill 创建后，根据实际使用进行迭代：
迭代工作流：
- 在真实任务上使用 Skill
- 注意困难或低效之处
- 确定如何更新 SKILL.md 或捆绑资源
- 实施更改并再次测试
参考资料
常见问题
Skill 不生效怎么办？
- 检查 Skill 是否在正确的目录（
~/.openclaw/workspace/skills/） - 检查 SKILL.md 的 frontmatter 格式是否正确
- 重启 OpenClaw Gateway
- 检查
description是否清晰描述了使用场景
如何调试 Skill？
- 查看 Gateway 日志
- 使用
openclaw skills list查看已加载的 Skill - 检查 AI 是否正确匹配到 Skill
Skill 可以分享吗？
可以！打包成 .skill 文件后，可以：
- 通过邮件/聊天分享给其他人
- 上传到 ClawHub 社区
- 发布到 GitHub