如何为 OpenClaw 开发自定义技能：循序渐进指南
OpenClaw 团队
为什么要构建自定义技能？
OpenClaw 虽然自带了一套强大的内置工具，但当您根据特定需求对其进行定制时，真正的魔力才会显现。无论您是想控制智能家居、集成内部专有 API，还是仅仅想自动处理繁琐的日常任务，自定义技能（Custom Skills） 都是最佳解决方案。
在本指南中，我们将带您从零开始创建一个新技能。
什么是技能？
在 OpenClaw 中，一个技能本质上就是一个包含两样东西的文件夹：
SKILL.md：定义文件，告诉 OpenClaw 如何使用该技能。- 脚本/可执行文件：执行实际操作的代码（Python, Bash, Node.js 等）。
这种模块化设计意味着您可以使用任何您喜欢的语言编写逻辑，只要它能在您的机器上运行。
第一步：创建技能目录
导航到您的 OpenClaw 技能目录（通常是 ~/.openclaw/skills 或您的工作区技能文件夹）。
mkdir -p my-new-skill/scripts
cd my-new-skill
第二步：编写逻辑
让我们创建一个简单的技能来获取随机励志名言。我们将以此为例使用 Python。
创建 scripts/quote.py：
import requests
import random
def get_quote():
quotes = [
"预测未来的最好方法就是去创造它。",
"代码就像幽默。如果你必须解释它，那就说明它很糟糕。",
"简单是效率的灵魂。"
]
print(random.choice(quotes))
if __name__ == "__main__":
get_quote()
确保它是可执行的：
chmod +x scripts/quote.py
第三步：定义技能 (SKILL.md)
现在，在技能文件夹的根目录下创建 SKILL.md 文件。这是技能的"大脑"。
---
name: daily-quote
description: 获取每日励志名言以开启新的一天。
---
# 每日名言
获取随机的励志名言。
用法:
```bash
python3 {baseDir}/scripts/quote.py
### 关键组件：
- **name**：技能的唯一标识符。
- **description**：帮助 AI 决定何时使用此工具。
- **usage**：AI 应该运行的确切命令。`{baseDir}` 是一个特殊变量，会解析为技能的路径。
## 第四步：注册与测试
重启 OpenClaw 或运行重载命令以加载新技能。
您现在可以问您的智能体：
> "给我一些灵感。"
OpenClaw 会看到"获取励志名言"的描述，将其与您的请求匹配，并执行 Python 脚本！
---
## 最佳实践
### 1. 安全第一
始终验证脚本中的输入。请记住，AI 正在您的机器上执行代码。
### 2. 保持无状态
技能理想情况下应该是无状态的。如果您需要存储数据，请使用工作区中的文件或数据库。
### 3. 清晰的输出
AI 会读取您脚本的标准输出 (stdout)。保持输出清晰易读。
---
## 哪些人最应该先做自定义技能？
这条路线尤其适合三类人：
- **每天都在重复同一类手工操作的运营者**，例如分发日报、整理线索、搬运数据或巡检固定面板。
- **需要调用内部 API 或私有系统的团队**，因为通用公共集成往往覆盖不到真正关键的内部流程。
- **已经知道“希望 OpenClaw 帮我执行哪个命令”的人**，只是还没有把它封装成一个可复用、可触发的技能。
如果您的工作流每周都在大变，先用提示词和手动步骤沉淀流程更划算。等动作已经稳定重复，再把它做成技能，回报通常更高。
## 上线前常见判断问题
### 什么时候技能比长提示词更合适？
当任务依赖确定性的命令、本地文件、环境变量、权限边界，或者固定的多步执行链路时，技能通常比长提示词更稳。如果任务核心仍然是“思考和写作”，先用提示词往往更轻。
### 第一个版本应该做多小？
通常比多数人想的还要小。一个好的第一版技能，最好只做好一件事，输出清楚，不隐藏副作用。如果还没跑通就需要接五个配置项和三套外部系统，范围大概率已经过头了。
### 给别人用之前至少要检查什么？
至少确认四件事：命令路径是否固定、依赖的环境变量是否写清楚、失败时会怎样退出、以及只看 stdout 能不能大致知道发生了什么。否则后续排障成本会很高。
## FAQ：什么样的自定义 skill 更容易长期维护？
### 一个 skill 真正进入日常使用后，最先坏掉的通常是什么？
通常不是脚本本身先坏，而是输入约定、输出格式和失败处理没有定义清楚。作者自己能跑通，不代表团队里其他人也能在不同文件、不同权限、不同上下文下稳定复用。
### 什么时候应该把一个 skill 拆成两个更小的 skill？
当一个 skill 同时承担两种不同意图时，就该拆了。比如一条命令一会儿做诊断，一会儿又直接改数据，或者一部分动作低风险，另一部分动作会影响生产环境，这时拆开通常更容易信任，也更容易排障。
### 上线后最值得盯的维护信号是什么？
看使用者是否越来越频繁地“必须打开脚本才能知道发生了什么”。如果只看 stdout 已经看不懂、大家反复追问缺哪个环境变量、或者输入略微变化就产生意外结果，这个 skill 基本已经超出了原来的接口边界。
## 如果你现在要把 skill 真正跑起来，下一跳先看哪两篇
如果你现在的目标不是继续看概念，而是尽快把一个 skill 做到“能安装、能调用、能排障”，建议按这个顺序继续看：
1. 先看 [OpenClaw 完整安装指南：自托管搭建、检查点与常见坑](https://www.openclawnews.org/zh/news/openclaw-complete-installation-guide)，先补齐 Node、gateway、首次启动和基本可用性检查，避免把环境问题误判成 skill 写坏；
2. 再看 [OpenClaw 智能体故障排查指南](https://www.openclawnews.org/zh/news/troubleshooting-openclaw-agents)，把 skill 调不起来、工具不回、权限不够、stdout 不清晰等问题和安装阶段的问题分开处理。
如果你已经能稳定跑通一个最小 skill，再回来看这篇的目录结构、输入输出和拆分边界，会更容易把它做成可复用资产。
## 上线前先做 4 个收口检查
即便 skill 已经能跑通一遍，也别直接发给团队大范围使用。至少先确认四件事：
1. 命令路径固定，文档里的调用方式和实际文件位置一致；
2. 依赖的环境变量、密钥或前置条件写清楚，别人不会靠猜；
3. 失败时会怎么退出，stdout / stderr 能不能让下一位值班同事快速判断问题；
4. 你已经在至少一个真实场景里复跑过一次，确认小改动不会把输入、输出或权限边界弄乱。
## 什么时候不要急着创建 skill
自定义 skill 很适合把稳定、重复、可验证的动作产品化，但不适合替代还没想清楚的流程。下面几种情况，建议先继续用提示词、手动 checklist 或一次性脚本：
1. 任务每次输入都不同，还没有稳定的成功标准；
2. 需要频繁改权限、密钥或生产数据，但还没有审批边界；
3. stdout 输出无法让下一位同事判断成功还是失败；
4. 只是为了包装一段很短的提示词，没有真正调用文件、命令或外部系统。
这能承接“OpenClaw custom skill best practices”“when to create an AgentSkill”这类高意图搜索，把读者从教程流量引导到更成熟的发布决策。
## 延伸阅读
- [OpenClaw 新技能：Token Optimizer 使用指南](https://www.openclawnews.org/zh/news/new-skill-token-optimizer)
- [2026 年最值得关注的 5 个 OpenClaw 技能](https://www.openclawnews.org/zh/news/top-5-openclaw-skills-2026)
- [OpenClaw 智能体故障排查指南](https://www.openclawnews.org/zh/news/troubleshooting-openclaw-agents)
---
## 总结
您刚刚扩展了 AI 智能体的能力。从部署脚本到日历管理，真正有价值的往往不是“能不能做”，而是“能不能稳定重复地做”。
查看 [OpenClaw Marketplace](https://github.com/openclaw/skills) 获取更多示例并分享您的作品。
## 让用户依赖前的 Skill 发布检查清单
在发布或分享自定义 OpenClaw skill 之前，先做一次小型 release check，让搜索进来的读者能把教程转成可运行资产：
1. 确认 `SKILL.md` 写清触发条件、明确不适用场景，并至少给出一个具体命令或工作流示例。
2. 把长参考资料、schema 和辅助脚本放进 `references/` 或 `scripts/`，避免主 skill 变成不可读长文。
3. 用全新 session 测试 skill，确认 agent 只在触发条件真正匹配时才选择它。
4. 在 skill 目录里记录 owner、更新频率和外部 API 限制，避免后续维护者靠猜。
这样 custom skills 才不会停留在第一次 demo，而是变成能长期带来搜索流量和实际采用的资产。
## 发布前先排查自定义 skill
发布自定义 OpenClaw skill 前，先跑一个小型失败 preflight，避免 skill 带来低质量流量或坏安装：
1. **触发匹配**：测试用户真实会输入的关键词，确认只有一个 skill 明确适用；描述重叠会把 agent 导进错误 instructions。
2. **路径解析**：如果 `SKILL.md` 引用了 scripts、templates 或 examples，所有相对路径都要从 skill 目录解析，并确认文件存在。
3. **工具边界**：列清楚哪些动作只读、哪些会写本地、哪些会调用外部 API，避免 agent 过度要权限或静默产生副作用。
4. **恢复提示**：写出 skill 中途失败时，用户应运行的最短诊断命令或手动检查点。
这样能把“如何创建 OpenClaw skill”的搜索流量转成可实施入口：先查匹配，再查文件系统，再查工具权限，最后查恢复路径。
## 发布自定义 skill 前的就绪检查清单
如果你是搜“create OpenClaw skill”或“custom AgentSkill guide”来到这里，不要先写一篇很长的 prompt 文件。一个能进生产的 skill 至少要过这张检查清单：
1. 明确触发词，以及哪些场景绝对不该激活这个 skill；
2. 保持主 `SKILL.md` 足够短，让 agent 能快速加载，把长示例移到 references；
3. 放一个最小 happy path 示例，再放一个失败处理示例；
4. 写清外部写入、rate limit、auth 要求和需要人类审批的边界；
5. 发布成可复用 workflow 前，先用一条真实用户请求跑通验证。
这能把 custom skill 搜索流量转成更安全的构建路径：读者带走的是激活规则、操作边界和验证闭环，而不是又一个泛泛的 prompt template。
