Skill 开发入门 - OpenClaw | JR Academy

Skill 开发入门

你可能觉得开发一个 Skill 很复杂？其实真不是。OpenClaw 的 Skill 说白了就是一个 SKILL.md 文件——对，就是个 Markdown 文件，里面写着给 Agent 的指令。我去年十一月第一次写的时候，从零到跑通大概十分钟，比我预想的简单太多了。当时还以为要写一堆 TypeScript 呢，结果发现就是写 Markdown...

Skill 到底是什么？

先纠正一个常见误解——Skill 不是 Node.js 模块，不是 TypeScript 代码。Skill 本质上是给 Agent 的一组 Markdown 格式的指令，告诉 Agent 在特定场景下应该怎么做。你可以理解为一份结构化的 prompt。

一个 Skill 就是一个文件夹，核心是里面的 SKILL.md 文件。当 Skill 被激活的时候，SKILL.md 的内容会被加载到 Agent 的上下文里——Agent 就会按照你写的指令来行动。

Skill 的结构

一个最小的 Skill 就这么简单：

my-skill/
├── SKILL.md            # 核心：YAML frontmatter + Markdown 指令
├── references/         # 可选：参考资料（数据文件、模板等）
│   └── api-docs.md
└── scripts/            # 可选：可执行脚本
    └── fetch-data.py

SKILL.md — 这才是核心

整个 Skill 的灵魂就在这个文件里。上半部分是 YAML frontmatter 声明元信息，下半部分是 Markdown 写的具体指令：

---
name: daily-weather
version: 1.0.0
description: 每天推送天气预报
author: your-name
category: productivity
requirements:
    - network
---

# Daily Weather Skill

你是一个天气查询助手。当用户询问天气相关问题时，按以下步骤操作：

## 查询天气

1. 从用户消息中提取城市名称
2. 使用 weather MCP 工具调用 WeatherAPI
3. 返回格式化的天气信息，包括温度、湿度和天气状况

## 输出格式

请用以下格式回复：

-   温度：XX°C
-   湿度：XX%
-   天气：晴/多云/雨...

## 注意事项

-   如果用户没指定城市，问他在哪个城市
-   温度默认用摄氏度，用户要求才转华氏度

几个关键字段：name 是唯一标识；version 遵循语义化版本号；requirements 声明需要啥能力（比如 network、filesystem 等）。Markdown 正文部分就是你给 Agent 的具体指示——写得越清晰 Agent 执行得越好。

这里有个大坑——Markdown 正文的质量直接决定 Skill 好不好用。跟写 prompt 一个道理，模糊的指令只会得到模糊的结果。我当时第一个 Skill 写得太简略了，就一句"帮用户查天气"，Agent 理解得一塌糊涂，后来把步骤拆细了才好起来。这个调试那章还会再讲。

references/ — 参考资料

这个目录放 Skill 需要的额外数据——API 文档、数据模板、示例文件之类的。Agent 在执行 Skill 的时候可以读取这些文件来获取更多上下文。比如你写了个"代码审查" Skill，可以在 references 里放一份编码规范文档，Agent 审查的时候就会参考它。

scripts/ — 可执行脚本

如果你的 Skill 需要跑一些代码逻辑（比如调 API、处理数据），可以放可执行脚本在这里。Python、Shell、Node 都行。Agent 会在需要的时候调用这些脚本。这个算是 Skill 里唯一涉及"写代码"的部分，但也不是必须的。

三种 Skill 类型

这个概念刚接触的时候可能会搞混，但其实很简单：

Bundled Skills — 随 OpenClaw 一起安装的内置技能。你装完 OpenClaw 就有了，不用额外操作。数量不多但覆盖了最常用的场景。

Managed Skills — 从 ClawHub（技能市场）安装的。clawhub install xxx 装上就能用，自动管理更新。存放在 ~/.openclaw/skills/ 目录下。

Workspace Skills — 本地项目级别的技能，放在当前项目的 ./skills/ 目录下。只在这个项目里生效。开发新 Skill 的时候用这种方式最方便，改了 SKILL.md 马上就能测，不用重新安装。

我自己开发 Skill 的流程就是先在 ./skills/ 里写 workspace skill，调试好了再发到 ClawHub。这样迭代速度最快。

Skill 怎么生效的？

Skill 被激活之后，SKILL.md 的内容会被加载到 Agent 的上下文里。说白了就是——你写的那些 Markdown 指令变成了 Agent 的"知识"，Agent 在对话中就会参考这些指令来行动。

Skill 激活 → SKILL.md 内容加载到 Agent 上下文
                    ↓
          Agent 在对话中参考这些指令
                    ↓
          需要执行操作时调用 MCP 工具或脚本

所以你会发现，Skill 的"能力"其实来自两方面：一是 SKILL.md 里写的指令（告诉 Agent 该怎么做），二是 MCP Server 提供的工具（让 Agent 能真正执行操作）。两者配合才能发挥作用。

补充一点：如果 SKILL.md 的 frontmatter 有语法错误（YAML 格式很严格的），Skill 会加载失败但不一定有明显报错。你猜怎么着？就是静悄悄地没生效，你还以为 Skill 在正常跑呢。Discord 里不少人被这个坑过，建议写完用 openclaw skills validate 检查一下。说实话我觉得官方这个默认行为设计得不太好，静默失败太坑了。

权限模型

Skill 的权限通过 SKILL.md frontmatter 里的 requirements 声明。目前支持这些：

network 管网络访问，调外部 API 用的。filesystem 管文件读写。shell 能执行 Shell 命令。cron 做定时任务。browser 控制浏览器做自动化。

就这五个，只申请你真正需要的。用户安装的时候会看到权限列表要确认的，权限要太多人家直接不装了嘛。

Skill 与 MCP 的关系

群里经常有人问这俩到底啥区别，我简单说啊——

Skill = Markdown 指令。 告诉 Agent 在特定场景下应该怎么思考、怎么行动。它本身不是代码，而是指导 Agent 行为的文本。用 SKILL.md 编写，clawhub install 安装，生态 5,400+ 个。

MCP Server = 代码工具。 用任意语言写的独立程序，通过 MCP 协议（stdio 或 HTTP）给 Agent 提供可调用的工具函数。可以是读数据库、调 API、操作文件系统——各种需要实际执行代码的操作。生态更大有 13,000+ 个，能跨 Claude Desktop、Cursor 等不同客户端用。

打个比方——Skill 是"菜谱"，MCP Server 是"厨具"。菜谱告诉厨师做菜的步骤和要点，厨具让厨师能真正切菜炒菜。一个好的 Skill 通常会配合一个或多个 MCP Server 来完成任务。

比如你写了个"代码审查" Skill，SKILL.md 里写明审查标准和流程，但实际读取代码文件、执行 lint 检查这些操作，是通过 filesystem MCP Server 和 shell MCP Server 来完成的。Skill 不需要自己实现这些工具——MCP 生态里已经有了，直接用就行。

Workspace 里的其他重要文件

除了 Skills，工作空间里还有几个重要的 Markdown 文件值得了解：

SOUL.md — 定义 Agent 的"人格"，比如说话风格、知识领域、角色设定
AGENTS.md — 给 Agent 的通用指令，适用于所有对话
USER.md — 用户偏好设置，比如语言、格式偏好等

这些跟 Skill 不同——Skill 是针对特定任务的指令，而这些文件是全局性的设定。

开发工具链

# 在当前项目创建 workspace skill（推荐开发用）
mkdir -p ./skills/my-skill
# 然后创建 SKILL.md 就行了

# 使用脚手架创建 Skill（会生成标准目录结构）
openclaw skills create my-skill

# 验证 Skill 配置（检查 frontmatter 格式等）
openclaw skills validate ./my-skill

workspace skill 的好处是改了 SKILL.md 保存就能测，迭代速度非常快。等调试好了再发到 ClawHub。