OpenClaw 自定义技能开发教程|会写 Markdown 就能开发,10 分钟打造专属技能

本系列第十六篇：从“用户”到“创作者”——你写的每一段说明，都是 AI 的执行蓝图

                欢迎回到 OpenClaw 系列教程。前面十五篇，你学会了安装、配置、装 Skills。现在的 OpenClaw 已经能完成很多任务了。

        但如果你问一个深度用户，最能让你愿意持续投入时间学这个项目的功能是什么？大部分人的回答会出奇一致——不是某个现成的 Skill 多好用，而是我终于可以自己写 Skill 了。

        在 OpenClaw 的 Skill 系统中，每一个技能只是一个 Markdown 文件。会打字就能开发，10 分钟就能做出第一个可运行、可复用、可分享的技能包。开发 Skill 的本质，不是写复杂代码，而是给 AI 一份清晰的“执行说明书”，教会它“什么时候用什么工具、按什么顺序干活”。

本篇将系统讲解自定义 Skill 的完整开发流程，从文件夹结构、SKILL.md 核心文件的编写，到进阶带脚本的技能开发，再到调试测试与发布分享。无论你是零代码用户还是资深开发者，都能找到适合自己的开发路径。

一、核心认知：Skill 到底是什么？

在动手之前，先建立三个关键认知，能帮你省掉后面 80% 的弯路。

        认知一：Skill 是一份“说明书”，不是一段程序。 Skill 不是后台插件，它不需要复杂的代码逻辑，核心就是一个带 YAML 元数据的 Markdown 文件。AI 读取后就知道“遇到什么情况时，按什么步骤做”。整个 Skill 就是一个文件夹，里面放一个 SKILL.md 文件，OpenClaw 通过这个文件理解技能的功能、触发条件和执行流程。

        认知二：Skill 专注于“怎么做”，不参与“理解什么”。 用户说的话由 OpenClaw 内核转成结构化指令，Skill 只负责接收标准化输入、执行具体操作、返回标准化结果。它不参与意图解析，不管理权限，专注于做好一件事。

        认知三：Skill 遵循三大设计理念。 OpenClaw Skill 的设计遵循三个核心理念：渐进式披露——YAML 元数据每次都加载（简洁高效），Markdown 正文仅在匹配时加载，链接文件按需加载，既节省 Token 又保证深度；可组合性——技能之间互不干扰，可同时启用；可移植性——按规范开发的技能可在多个平台通用。

二、两种开发路径：你属于哪一类？

OpenClaw 支持两种 Skill 开发路径，你可以根据自己的技术水平选择合适的起点：

路径一：自然语言 Skill（零代码，推荐新手）

• 只需要编写 Markdown 文件，通过说明性指令定义工作流

• 适合纯流程指引类任务，如文档处理建议、工作流指导

• 学习成本最低，10 分钟可完成第一个技能

路径二：TypeScript/脚本 Skill（需编程基础）

• 用 TypeScript 编写核心逻辑，可访问 API、执行复杂计算

• 适合需要调用外部服务、处理数据的复杂任务

• 遵循“3 文件核心结构”：plugin.json（元信息）+ index.ts（执行逻辑）+ package.json（依赖）

        本文将从零代码的自然语言 Skill 开始，再讲解带脚本的进阶技能开发。选择哪条路径，取决于你的任务复杂度和编程基础。

三、你的第一个 Skill：Hello World

我们先从最基础的“打招呼”技能开始，掌握完整的开发与测试流程。

3.1 创建 Skill 目录

Skills 可以放在两个位置，根据需求选择：

bash

# 方法1：在工作区创建（推荐新手，只对当前工作区有效）mkdir -p ~/.openclaw/workspace/skills/hello-world# 方法2：在全局目录创建（对所有工作区有效）mkdir -p ~/.openclaw/skills/hello-world

        优先级规则：<workspace>/skills/ > ~/.openclaw/skills/ > 内置 Skills，同名时高优先级覆盖低优先级。新手推荐先在工作区创建，方便调试。

3.2 编写 SKILL.md

在 hello-world/ 目录下创建 SKILL.md 文件，写入以下内容：

markdown

---name: hello_worlddescription: A simple skill that says hello when the user asks for a greeting.---# Hello World SkillWhen the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!"

        frontmatter（YAML 部分）中的 name 和 description 是必填字段，name 使用 snake_case 命名，description 提供一行简要描述，供 AI 判断是否调用此技能。Markdown 正文包含面向 AI 的执行指令。

3.3 加载并测试

创建完成后，需要让 OpenClaw 发现新技能：

bash

# 方法1：在聊天界面输入 /new 开启新会话# 方法2：重启 Gatewayopenclaw gateway restart# 验证技能已加载openclaw skills list

测试技能：

bash

# 命令行测试openclaw agent --message "give me a greeting"# 或在聊天界面发送 "打个招呼"

看到 “Hello from your custom skill!” 的回复，说明你的第一个技能创建成功了。

四、SKILL.md 标准结构详解

一个规范的 SKILL.md 应包含以下五个核心部分，缺一不可。

4.1 描述信息

清晰简洁地概述 Skill 的功能和用途，帮助用户理解技能的价值：

markdown

# Weather Query Skill一个可以查询全球任意城市实时天气和天气预报的技能。使用 wttr.in 服务，无需 API Key。

4.2 触发器

定义哪些用户关键词会激活这个 Skill，应与技能功能密切相关：

markdown

## 什么时候使用 ✅当用户提到以下内容时激活此技能：- "今天天气怎么样？"- "北京会下雨吗？"- "查询上海的天气"- "纽约的温度是多少"## 什么时候不要使用 ❌- 需要历史天气数据- 需要极端天气预警

在 frontmatter 的 description 中也可以用精简的一行传递触发条件信息，供 AI 快速判断。

4.3 使用说明

详细的执行步骤，确保逻辑清晰、步骤完整，让 AI 知道按什么顺序做什么事：

markdown

## 使用说明1. 识别用户查询的城市名称2. 使用 `curl` 命令调用 wttr.in API3. 解析返回的天气数据4. 用自然语言向用户汇报结果

4.4 环境变量

列出技能需要的环境变量，帮助用户了解配置需求：

markdown

## 环境变量- `REPORTS_DIR`：日报存储目录（默认 `~/reports`）- `WEATHER_API_KEY`：天气 API 密钥（如需）

4.5 所需工具

明确列出运行该技能需要的工具，方便用户提前准备：

markdown

## 所需工具- `curl`：HTTP 请求工具- `jq`：JSON 解析工具（可选）

五、实战案例一：自然语言天气查询 Skill

我们通过一个完整的天气查询技能，把刚才的五个部分串起来。

完整的 SKILL.md 如下：

markdown

---name: weather_querydescription: Query real-time weather and forecasts for any city. Use when user asks about weather, temperature, or forecasts.homepage: https://wttr.in/metadata:  openclaw:    emoji: "☁️"    requires:      bins: ["curl"]---# Weather Query Skill使用 wttr.in 服务查询全球任意城市的天气信息。**无需 API 密钥**。## 什么时候使用 ✅- "今天天气怎么样？"- "北京会下雨吗？"- "查询上海的天气"- "纽约的温度"- 旅行前查询目的地天气## 什么时候不要使用 ❌- 需要历史天气数据- 需要极端天气预警- 需要航空/海洋专业天气## 查询命令### 实时天气（简洁版）```bashcurl "wttr.in/城市名?format=3"

示例：curl "wttr.in/Beijing?format=3" → 输出：Beijing: ☀️ +25°C

详细天气（含湿度、风力）

bash

curl "wttr.in/城市名?format=%l:+%c+%t+%h+%w"

响应模板

用户查询天气后，按以下格式回复：

城市名：天气状况 🌡️ 温度 💧 湿度 🌬️ 风速 例如：北京：☀️ 晴天 +25°C，湿度 45%，风速 12 km/h

text

将上述内容保存为 `~/.openclaw/workspace/skills/weather_query/SKILL.md`，执行 `openclaw gateway restart` 后即可使用。以后在聊天中输入“今天北京天气怎么样”，OpenClaw 就会自动调用这个技能，通过 curl 查询 wttr.in 并返回格式化的天气信息。  

六、实战案例二：带脚本的进阶 Skill（币价监控）

        当技能需要更复杂的逻辑——调用外部 API、处理数据、发送通知——就需要引入脚本。我们以“查询加密货币价格”为例，演示完整流程。

6.1 准备工作

需要 Node.js 环境（v18+）和一个币价 API Key。推荐使用 CoinGecko 的免费 API。

bash

  # 注册获取 API Key（可选，免费版无需 Key）  # 访问 https://www.coingecko.com/en/api

6.2 创建目录结构

一个带脚本的复杂技能通常包含以下结构：

bash

mkdir -p ~/.openclaw/workspace/skills/crypto-price/scriptscd ~/.openclaw/workspace/skills/crypto-price

6.3 编写执行脚本（TypeScript）

创建 scripts/fetch-price.ts：

typescript

#!/usr/bin/env node// 获取命令行参数const coin = process.argv[2]?.toLowerCase() || 'bitcoin';const currency = process.argv[3]?.toLowerCase() || 'usd';async function fetchPrice() {  try {    // 调用 CoinGecko API（免费，无需 Key）    const url = `https://api.coingecko.com/api/v3/simple/price?ids={currency}`;    const response = await fetch(url);    const data = await response.json();    if (data[coin] && data[coin][currency]) {      const price = data[coin][currency];      console.log(`{price.toLocaleString()} {coin} 的价格信息。支持币种: bitcoin, ethereum, solana 等`);    }  } catch (error) {    console.error('获取价格失败:', error.message);  }}fetchPrice();

6.4 编写 SKILL.md

markdown

---name: crypto_pricedescription: Query cryptocurrency prices from CoinGecko API. Use when user asks about crypto prices, bitcoin price, ethereum value, etc.metadata:  openclaw:    emoji: "₿"    requires:      bins: ["node"]---# Crypto Price Skill查询加密货币的实时价格。使用 CoinGecko API，免费且无需 API Key。## 什么时候使用 ✅- "比特币现在多少钱？"- "查一下以太坊价格"- "SOL 的价格是多少"- "狗狗币今天涨了吗"## 支持币种bitcoin, ethereum, solana, dogecoin, cardano, ripple, polkadot 等主流币种。## 使用命令```bashnode ~/.openclaw/workspace/skills/crypto-price/scripts/fetch-price.js <币种> <货币单位>

示例：

• node scripts/fetch-price.js bitcoin usd → BTC 当前价格

• node scripts/fetch-price.js ethereum cny → ETH 人民币价格

响应模板

用户查询后，执行脚本并返回价格信息：

币种名称 当前价格: X,XXX 货币单位

如果币种不支持，返回可用的币种列表提示。

6.6 安装依赖（TypeScript 脚本需要）

```bash 

cd ~/.openclaw/workspace/skills/crypto-pricenpm init -ynpm install typescript @types/node --save-devnpx tsc scripts/fetch-price.ts --outDir scripts --target es2020 --module commonjs

将 TypeScript 编译成 JavaScript 后，OpenClaw 即可执行。

6.6 测试技能

bash

# 直接测试脚本node scripts/fetch-price.js bitcoin usd# 输出示例: BITCOIN 当前价格: 65,432 USD# 通过 OpenClaw 测试openclaw agent --message "比特币现在多少钱？"

七、开发最佳实践

        简洁是最高原则。 上下文窗口是公共资源，技能需要与系统提示、对话历史和其他技能的元数据共享。只添加模型还没有的上下文，优先使用简洁的示例而非冗长的解释。

        设置适当的自由度。 根据任务的脆弱性和可变性匹配详细程度：当有多种有效方法、决策依赖于上下文时使用高自由度（基于文本的指令）；当操作脆弱且容易出错、一致性至关重要时使用低自由度（特定脚本，少量参数）。

        安全优先。 如果技能使用 exec 或 bash，确保提示词不会允许来自不可信输入的任意命令注入。对于需要外部 API 调用的技能，建议将 API Key 通过环境变量传入，不要硬编码在脚本中。

        本地测试后再分享。 在分享到 ClawHub 前，使用 openclaw agent --message "..." 进行充分测试。

        循序渐进。 建议先从简单的 Skill 入手，比如本文的 Hello World 和天气查询，逐步探索更复杂的功能实现。

八、调试与排错

        技能未被发现。 确认目录结构正确，SKILL.md 文件名完全匹配（大小写敏感），然后执行 openclaw skills list 查看是否在列表中。

        配置修改后未生效。 在聊天界面输入 /new 开启新会话，或执行 openclaw gateway restart 重启 Gateway。

                脚本执行报错。 确保脚本有执行权限：chmod +x scripts/your-script.js；确认 Node.js 版本 ≥ v18；在命令行直接运行脚本，确认逻辑无误。

        AI 不调用我的技能。 检查 SKILL.md 中的 description 是否清晰描述了触发条件；在聊天中明确使用触发词；检查技能是否被其他同名技能覆盖。

九、分享与发布

技能开发完成并充分测试后，可以通过 ClawHub 分享给社区。

        发布前准备。 确保 SKILL.md 包含完整的描述、触发条件、使用说明、环境变量和所需工具；确保文件夹结构清晰，SKILL.md 格式正确。

        注册并发布。 访问 ClawHub 注册账号并验证邮箱；登录后进入“上传 Skill”页面，上传技能文件夹；填写技能名称、描述、版本号等信息；提交审核，等待 ClawHub 团队验证。任何人都可以上传技能，但 GitHub 账户必须至少创建一周后才能发布，这有助于减缓滥用。

        版本管理。 技能发布后，可以通过 ClawHub 进行版本管理，支持更新和回滚。定期查看用户评分和评论，根据反馈持续优化。

十、下一步做什么？

恭喜！你已经掌握了从零开发 OpenClaw 自定义技能的全部流程。接下来可以根据需要继续探索：

• 第 17 篇：OpenClaw 插件开发进阶——理解 Plugin → Hook → Skill 三层扩展体系

• 第 18 篇：OpenClaw 技能编排实战——如何组合多个技能完成复杂任务链

• 第 19-22 篇：多平台集成——微信、飞书、Telegram 等渠道接入

• 第 27 篇：安全配置指南——沙箱隔离、执行审批与权限最小化最佳实践

💡 最终提醒：Skill 开发的核心不是代码能力，而是把“你想让 AI 怎么做事”清晰地写成 AI 能理解的说明书。从最简单的 Hello World 开始，慢慢迭代，你很快会发现——OpenClaw 的能力边界，只取决于你的想象力。