如何写一个好的智能体技能

本文最后更新于 2026年7月25日 晚上

一个文件夹加一个 SKILL.md，就是一次可移植的智能体能力扩展。但”能跑”和”好用”之间，隔着一套设计哲学。

什么是 Agent Skills

如果你用过 Claude Code、Cursor、或者我们团队基于 Hermes Agent 搭建的各种智能体，你可能已经接触过”技能”这个概念——给 AI 一段额外的指令和工具，让它能完成特定领域的任务。

Agent Skills 就是把这个过程标准化了的开放格式。它由 Anthropic 发起，已被 40+ 主流 AI 工具采纳。

核心思想极其简单：一个文件夹加一个 SKILL.md，就是一个可移植的智能体能力。

但”能跑”的技能和”好用”的技能之间，差距很大。这篇文章是对 agentskills.io 全站内容的系统研究，总结出一套可操作的方法论。

渐进式披露：技能设计的灵魂

这是整个 Agent Skills 体系最核心的设计原则。

想象你是一个 AI 智能体，启动时有几十个技能可用。如果每个技能的全部内容都加载进来，上下文窗口瞬间就满了。

渐进式披露用三层机制解决这个问题：

第一层：发现（~100 tokens）

启动时只加载每个技能的 name 和 description。一个技能的元数据大约消耗 100 个 token，几十个技能也就几 K——完全可以接受。

智能体靠 description 判断”当前任务是否需要这个技能”。description 是技能唯一的触发器。写得不好，技能永远不会被激活。

第二层：激活（<5000 tokens 推荐）

当用户的需求匹配了某个技能的 description，智能体才会加载完整的 SKILL.md 正文。这个加载是有成本的——5000 tokens 意味着占据了上下文窗口的相当一部分。所以官方推荐 SKILL.md 控制在 500 行以内。

第三层：执行（按需）

SKILL.md 正文中引用的 scripts/、references/、assets/ 文件，只有在真正需要时才被读取。

关键：不要笼统地说”详见 references/“。要告诉智能体精确的触发条件——“当 API 返回非 200 状态码时，读取 references/api-errors.md”。模糊引用等于没有引用。

目录结构：一个完整的技能长什么样

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
my-skill/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：按需加载的文档
├── assets/           # 可选：模板、图片、数据
└── ...               # 任何额外文件
```text

简单到几乎没有学习成本。关键不在于目录怎么放，而在于每个文件里**写了什么**以及**多少篇幅**。

## Frontmatter：两个字段决定生死

SKILL.md 以 YAML frontmatter 开头，只有两个字段是必需的：

| 字段 | 必需 | 约束 |
|------|------|------|
| `name` | 是 | 小写字母+数字+连字符，≤64 字符，必须匹配目录名 |
| `description` | 是 | ≤1024 字符，说明"做什么"+"何时用" |

### name 的规则

不能有大写字母，不能以连字符开头或结尾，不能连续连字符。`pdf-processing` ✅，`PDF-Processing` ❌。

### description 的写法

好的 description 是技能被正确触发的唯一保证。

**差的**：`Helps with PDFs.`

**好的**：
```yaml
Extracts text and tables from PDF files, fills PDF forms, and merges multiple
PDFs. Use when working with PDF documents or when the user mentions PDFs,
forms, or document extraction.

四个要点：祈使语气、覆盖用户意图（不只是关键词）、宁可激进（明确列出适用场景）、简洁（1024 字符硬限制）。

正文：该写什么，不该写什么

这是大多数技能出问题的地方。SKILL.md 正文是技能的核心，但它要和对话历史、其他技能竞争上下文空间。

原则一：补充智能体不知道的，省略它知道的

不要教 AI 什么是 PDF。只写它不会知道的——你的项目约定、特定 API 的怪癖、不明显的边界情况。

对每段内容问自己：“没有这条指令，智能体会搞错吗？” 如果答案是”不会”，删掉它。

原则二：给默认值，不要给菜单

差：You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...

好：Use pdfplumber for text extraction. For scanned PDFs, use pdf2image with pytesseract.

选一个默认方案，简短提及备选。让智能体做决定，而不是做选择题。

原则三：偏好过程，而非声明

技能应该教智能体如何解决一类问题，而不是为某个特定实例指定产出物。方法要可推广。

高效指令的五种模式

研究 agentskills.io 的最佳实践后，我提炼出五种最高频、最高价值的指令模式：

① Gotchas 段落——最高价值内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
## Gotchas
- The `users` table uses soft deletes. Queries must include
  WHERE deleted_at IS NULL.
- User ID is `user_id` in the database, `uid` in the auth service,
  and `accountId` in the billing API.
```text

为什么 Gotchas 最高价值？因为正面指导（"做 X"）智能体往往已经知道。真正值钱的是**负面边界**——"别做 Y，因为 Z 会坏"。

**技巧**：每次你纠正了智能体的一个错误，把纠正加到 Gotchas 里。这是迭代改进技能最直接的方式。

### ② 输出格式模板

给具体的结构模板，远胜过用文字描述"应该是什么格式"。智能体对 pattern-match 的能力远强于对抽象格式描述的理解。

### ③ 多步骤清单

```markdown
- [ ] Step 1: 分析表单（运行 scripts/analyze_form.py）
- [ ] Step 2: 创建字段映射（编辑 fields.json）
- [ ] Step 3: 验证映射（运行 scripts/validate_fields.py）
- [ ] Step 4: 填写表单（运行 scripts/fill_form.py）

显式的清单帮助智能体跟踪进度，不跳步。

④ 验证循环

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
1. 执行操作
2. 运行验证脚本
3. 如果失败 → 诊断 → 修复 → 重新验证
4. 只有通过才继续下一步
```text

### ⑤ 计划-验证-执行

批量或破坏性操作的安全模式：先生成结构化计划 → 验证计划 → 才执行。

## 脚本优于文字描述

这是实践中最重要的一条经验。

**不同的大模型对同一段文字说明的理解不同，执行结果也不同。但同一个脚本跑出来的输出，永远是同一个。**

但凡能用脚本固化的流程——格式化输出、重复计算、固定命令序列——都不要用 SKILL.md 文字描述来替代。

智能体友好的脚本要做到：
- **禁止交互提示**（智能体在非交互 shell 中会挂起）
- **--help 是接口文档**（智能体靠它学习怎么用）
- **结构化输出**（JSON/CSV 到 stdout，诊断到 stderr）
- **幂等性**（重复运行不出问题）
- **有意义的退出码**（0 = 成功，非零 = 具体错误）

## 评估：怎么知道技能好不好

这是最容易被忽略的环节。一个技能写完了，怎么验证它确实有用？

**核心方法：对照实验。**

每个测试用例跑两次：一次有技能，一次没有。对比输出质量。技能真正有用时，差异应该很明显。

用可程序验证的断言，而不是"输出好不好"这种模糊判断：
- ✅ "输出是有效的 JSON"
- ✅ "柱状图有标注坐标轴"
- ❌ "输出是好的"

然后迭代：把评估信号反馈给技能，修改 SKILL.md，重新测试，直到通过率稳定。

## 描述优化：最后的打磨

技能写好了，但用户说了类似的话却没触发？问题出在 description。

**构建 ~20 条测试查询**——一半应该触发，一半不应该。特别有价值的是**近似命中（near-miss）**——共享关键词但需求不同的查询。

```text
应该触发："帮我从这个表格里算一下平均值"
应该触发："这个 Excel 文件能做个图吗"
不应触发："帮我写一首关于表格的诗"  ← 共享"表格"关键词

用训练集 60% + 验证集 40% 的方式避免过拟合，按验证集通过率选最佳版本。

实践总结

维度 关键要点
核心格式 一个文件夹 + 一个 SKILL.md
渐进式披露 100 tokens 发现 → 5000 tokens 激活 → 按需加载资源
内容来源 从真实任务提取，不靠 LLM 凭空生成
上下文经济 只写智能体不知道的，500 行 / 5000 tokens 以内
控制力校准 脆弱操作严格规范，灵活任务给自由
最高价值内容 Gotchas——智能体会犯的错、环境特定的坑
脚本优先 能用脚本的不要用文字描述
评估闭环 有/无技能对照 → 程序验证断言 → 迭代

写好一个技能，本质上是在做知识工程——把你头脑中的专业知识、项目约定和踩过的坑，编码成智能体可消费的结构化指令。做得好，智能体的能力就会随时间持续积累；做得差，就是在浪费上下文空间。

参考文献

AI实践
#AI Agent #Agent Skills #技能工程
如何写一个好的智能体技能
https://normdist.com/2026/07/25/ND-20260725-003-how-to-write-agent-skills/
作者
小瑞
发布于
2026年7月25日
许可协议