Skill on Code Plato

Agent Skill 制作手册 01：入门篇

Thu, 28 May 2026 00:00:00 +0000

Agent Skill 制作手册是一个系列教程。这是第一篇。

什么是 skill

很多程序员问，Agent Skill 是什么？我敢说，Agent Skill 是你们学习编程以来能学到的最简单的技术之一。

skill 是怎么发展出来的

就像跟人一起工作一样。你有一个新入职的同事，就算他技术再好，也总要先看一些你们公司的 how to 文档，才能开始做事。人们发现，跟 LLM 工作也有同样的模式。你让 LLM 直接做事情，那多半会做出一件偏离你预期的漂亮事，这就很尴尬了。

然后就有人发现，如果先在提示词里面加上做事情的步骤，LLM 就做得好。所以大家就一直给 LLM 喂 how to 手册。

但是 LLM 的上下文有限啊，而且你每次塞这么多上下文，你的钱包先爆了。于是人们又想，其实我们自己工作的时候也记不住 how to 的内容。我们大概记得有那么个 how to 教了我做这件事情，但具体内容不记得了。没关系啊，我们到时候再去 wiki 看看不就得了。那我们也可以让 LLM 只记住这个 how to 是做什么的，具体需要的时候再看呗。于是我们可以把每一个 how to 的描述喂给 LLM，LLM 看描述就知道，需要做事情的时候要找哪个 how to 了。

到这里，我们已经可以推导出一个简单的、给 LLM 量身定做的 how to 了。它只有两个重要属性：name 和 description，剩下的就是正文了。每次加载只加载 name 和 description，LLM 自己会判断是否需要读取这个 how to 的正文。

这就是 skill。其实这个东西叫什么不重要，它可以叫 howto、guide、manual 都可以，但是大家觉得 skill 这个名字够短、好记，还自解释，就用它了。可能在别的平行宇宙里，它叫 guide。

skill 是哪家的？

这种 SKILL.md 形态的 Agent Skill，最早是 Anthropic 系统公开推广的；但 skill 这个词和"让 AI 学技能"的思想并不属于某家公司。OpenAI、OpenClaw、Hermes Agent 都有自己实现的 skill。这只是一个概念，各家有各家自己的实现，这些实现在细节上有些区别，但都是指同一个事情。

怎么写 skill

skill 通用规范

各家的 skill 规范的共同点是：skill 是一个文件夹。结构是：

my-skill/
 SKILL.md # 必须：元数据 + 指令
 scripts/ # 可选：可执行脚本
 references/ # 可选：文档、说明、规范

而其中的 scripts、references 都不是必须的，只是大家习惯的一种最佳实践而已。最重要的是 SKILL.md。有的 skill 只有这一个文件，而这个文件的结构也很简单。

一个最小的 SKILL.md，在元数据层面只需要 name 和 description。正文可以很短，但最好写清楚 agent 被触发后到底要做什么。

---
name: skill的名字
description: 解释这个skill是干嘛的，什么时候应该被触发，什么时候不应该被触发等
---

当你的 skill 比较复杂，需要一些结构化的数据和逻辑的时候，就可以考虑建立 scripts 文件夹，然后在里面写代码。当你的 skill 引用的文档比较多，你怕把上下文给撑爆了，就可以把大部分文档移到 references 里面。

写一个 skill

来动手写一个 skill 吧。我保证这是你看到的最短的教程。这个 skill 会在你说三次 Hello 的时候回复三个 World。新建 SKILL.md，并在里面写：

---
name: hello-world
description: 当用户说三次"Hello"（例如"Hello Hello Hello"）时，回复三次"World"："World World World"。
---

# Hello World

当用户的消息中包含恰好三个"Hello"时，只回复：

World World World

不说其他任何内容，只有这三个字。

然后安装到你的 AI agent 里面。你问我怎么安装？这都什么年代了，你问你自己的 AI agent 怎么安装，它自会告诉你的。

安装好后就试试吧。

skill 规范

Codex、Claude Code、OpenClaw、Hermes Agent 它们都对 skill 有自己的一些细节上的规范，我就不在此赘述。不过有几点我觉得有必要提。

Skill 防触发机制

基本上，是否触发 Skill 是看 LLM 自己决定的。这其实带来另外一个问题，就是 skill 经常被误触发，或者不被触发。对此各家都有各自的措施。

禁止自动触发，但允许手动触发
- Claude / OpenClaw: disable-model-invocation: true
- Codex: agents/openai.yaml 里的 allow_implicit_invocation: false
彻底禁用 skill
- Codex: [[skills.config]] enabled = false
- OpenClaw: skills.entries.<skillKey>.enabled = false

从这里可以看出，skill 的优点在于自由，但缺点也是自由。有时候你想触发，却触发不了；不想触发，它却一直被触发。不过在之后的教程中我会介绍一些范式来解决这个问题。

Skill 的分类

在 skill 慢慢被越来越多的人使用后，skill 也开始出现一些分类方式。

skill 和 command

在 OpenClaw 和 Claude 桌面版中，skill 是可以用斜杠（/）调用的。区别在于，在 Claude 桌面版中，你安装了 Skill 后，按 / + <skill名> 就可以触发 skill；而在 OpenClaw 中，你是通过设置 user-invocable: true 来让这个 skill 可以用斜杠触发的。

在 OpenClaw 里，一部分 skill 可以被暴露成 slash command。command 是调用方式，不一定是独立分类。这就引发了一个有趣的思考：当你建立一个新 skill 的时候，你可以思考一下，你这个 skill 是一个普通的 skill，还是一个 command。毕竟在手机上找到斜杠，并不像在电脑上这样容易。有些生活类的 skill，你可以依赖 LLM 去猜测；而有些需要精确被触发的，就可以用斜杠。

工作流式和应用式

你会发现，有些 skill 仅仅只是定义了一件事情该怎么做，而有些 skill 更像是一个你自己定义的 app。定义了该怎么做的，可以被称为工作流式。

比如你让 LLM 帮你归纳一下会议纪要。这样的 skill 就只需要 SKILL.md 就够了。如果流程比较复杂，那就把流程抽取到 references 里面。
如果是应用式的，比如你要做一个购物清单，你需要比较复杂的逻辑和比较规范的数据存储。你就需要将某些逻辑抽取出来写成 scripts。但是 scripts 不是越多越好，只有需要确定性行为或外部工具时才用 scripts。

[一天一个Skill]第1天：查单词Skill

Sat, 09 May 2026 00:00:00 +0000

即读即弃

即读即弃是我的写作风格。

我不是按照瀑布式的方式写文章的。所谓瀑布式，就是把整篇文章拆成多个步骤，你必须一路读到最后才能做出一个完整的东西。如果读到一半弃了，那就只能得到一个半成品。

现在这个时代节奏太快了，我自己都没时间长时间阅读一篇文章。我的文章是迭代式的。你看一小段，就可以先做出一个东西，然后我们再继续扩展，把这个东西做得更好。你如果没时间，就看多少算多少。

所以我会把文章分成多个部分。每读完一个部分，如果你不想继续往下读，就可以直接弃了下课。

第一部分：一个简单的查单词 Skill

背景知识

Skill 是什么

Skill 是 Claude 的母公司 Anthropic 在 2025 年底提出的一个规范。

支持这个规范的工具很多，比如 openclaw、codex、claude code 等等。

你不一定要跟我用同样的工具。只要你的 agent 智能体支持 Skill，就可以使用。

学会方法之后，你自己装到自己的智能体里就行了。不懂怎么装，就直接问你的智能体。

都什么年代了，别再"百度一下"“Google 一下"了，太低效了。

如果你的智能体回答不上来，或者一直回答错，那就考虑换一个智能体吧。

个人习惯

我个人喜欢用 openclaw，因为它是目前最接近"下一代普通人个人智能体"的东西，对生活帮助很大。

但 openclaw 太不稳定了，不适合演示，所以这里我会用 claude code。

痛点

如果你只是把一个单词直接发给 AI，它通常会按自己猜测的意思返回结果。

比如你想查 apple 这个单词，你直接对 AI 说：

apple

它大概率会返回：

Apple 是一家美国科技公司，总部位于美国加州库比蒂诺（Cupertino）。

它最著名的产品包括：

- iPhone
- MacBook
...

所以我们可以做一个专门查单词的 Skill。

开始制作 Skill

建立一个文件夹：en-cn-dict
在文件夹里面建立文本文件 SKILL.md

SKILL.md 内容

---
name: 查单词
description: 当用户消息中出现"查单词："或"查单词:"后跟英文单词时，返回音标、中文解释和发音。
---

## 处理规则

提取冒号后面的英文单词或短语。

兼容中文冒号 `：` 和英文冒号 `:`。

## 输出格式

必须严格使用以下格式：

单词：<英文单词>

音标：<音标>

中文解释：
1. <解释1>
2. <解释2>
3. <解释3>

部署 Skill

然后把这个文件夹放到：

~/.claude/skills/

里面。

如果没有 skills 文件夹，就自己创建一个。

部署完成后的路径：

skills
 ⎿ en-cn-dict
 ⎿ SKILL.md

加载 Skill

现在重启 claude code，然后问它：

查单词：tea

可以看到，它加载了 en-cn-dict 这个 Skill。

第一部分完成。

第二部分：真正的 Skill 编写方式

AI 时代最大的改变之一就是：

不要自己手写代码。

我们一定要慢慢改掉"所有东西都手写"的习惯。

其实 Skill 也一样，应该让 AI 自己去写。

比如我们这个查单词 Skill，本来就应该让 agent 自己生成。

如果你用的是 codex、openclaw、claude code 这种 agent 工具，你甚至可以直接让 agent 完成整个 Skill 的构建过程。

如果你只有 ChatGPT、Claude、Gemini 这种 chat app，那你就手动创建文件，然后让 chat app 告诉你 SKILL.md 该怎么写。

我这里用 claude code 演示创建 Skill。

我对 claude code 说：

claude code 帮我把 Skill 文件创建好了：

现在测试一下。

成功了。

不过它还是输出了一些我们没要求的内容。

AI 写代码就是会自由发挥。不过没关系，多出来的东西如果你不要，就继续让它删掉就好了。

第三部分：编写 Skill 的常用模式和问题

触发词

在这个例子里，我用了"触发词"的模式。

因为 agent 本质上是一个什么都能聊的对话框。什么都能说的代价，就是很容易混乱。

有时候 agent 并不能自动判断该使用哪个 Skill。

这时候你就可以通过"触发词"来缩小范围，精准定位要使用的 Skill。

这个触发词，有点像你手机里的一个 App 图标。你通过触发词，把 agent 导航到对应的 Skill。

如果你去看别的 Skill 入门教程，多半会看到"总结会议内容"这种例子。

那些教程里的 Skill 经常会写：

直接说"帮我总结会议"或类似请求

这里其实有两个问题：

太长，不好记
“或类似请求"以后会给你带来麻烦

你的 Skill 最好有一个：

简短
明确
不歧义

的触发词。

因为当你的 Skill 越来越多的时候，“类似请求"这种模糊匹配，会慢慢变成不确定因素。

触发词抢夺

有了触发词，就会有"触发词抢夺"问题。

我在 openclaw 里做这个例子的时候，它死活不按我的 Skill 来。

原因是：

我的 openclaw 用的是 OpenAI 的 API。

而"查单词：“这个词，在我使用的 model 里，本身就有很高的默认优先级。

这个 model 每次看到"查单词”，就会强行用自己的理解来处理。

这种现象，我把它叫做：

“触发词抢夺”。

如果遇到这种问题，也不用慌。

因为这通常说明：

其实 model 自己已经能很好地完成这件事了。

你甚至可能根本不需要专门做这个 Skill。

如果你真的想强制自定义，就换一个非常特殊、不容易被模型误判的触发词。

Skill 标记模式

如果你用的是 claude code，它会显式告诉你调用了什么 Skill。

但如果你用的是别的工具，比如 openclaw，它通常不会告诉你到底用了哪个 Skill。

这样就会让人很不安心。

你根本不知道它到底有没有调用你的 Skill。

这时候，你可以在 Skill 输出的最后，强制加一句：

使用了 [xxx skill]

这样你就能知道：

它到底有没有真正调用你的 Skill。