写了6个Skill才搞明白：AI Agent的Skill到底怎么写

Wed, 10 Jun 2026 10:00:00 +0800

我第一个Skill写了3遍才跑通——frontmatter格式错了、description超长、目录结构不对。踩完所有坑后，整理出这套编写流程。

先说结论

Skill 就是给 AI Agent 写一份"操作手册"。

写好了，Agent 遇到特定场景自动加载，按手册执行——不用你每次手把手教。

核心就是3件事：触发条件写清楚、操作步骤写具体、踩过的坑写进去。

下文用一个真实示例——“Markdown转微信公众号HTML”——走完整个编写流程。

你可以在读完后直接照着写自己的第一个 Skill，不需要任何前置知识。

Skill 是什么，为什么值得写

类比：你给新员工写了一份SOP——遇到什么情况、怎么处理、要注意什么。 Skill 就是给 Agent 的 SOP。

没有 Skill 的 Agent，你每次都要从头说： “先把Markdown转成HTML，注意微信不支持style标签，列表不能用ul……” 说一遍两遍还行，说十遍呢？

有 Skill 之后：Agent 识别到"公众号排版"任务，自动加载你的排版规范，直接按规范输出。你只需要说"把这篇文章排成公众号格式"。

Skill 的加载机制：

Agent 每轮对话前，会做一件事—— 扫描所有已安装 Skill 的 description 字段，和当前任务做语义匹配。匹配度够高，就自动把整个 SKILL.md 加载到上下文里。

这意味着两件事：

description 写什么，决定了 Skill 在什么场景被触发——写得准，精准触发；写得泛，要么不触发，要么乱触发
SKILL.md 的内容就是 Agent 的"即时记忆"——加载后 Agent 相当于突然"想起"了你写的所有规则和模板

Skill 能装什么：

内容类型	说明	示例
操作流程	Step-by-step怎么做	md转html的完整转换规则
代码模板	可直接复制的代码片段	微信HTML排版模板
踩坑清单	“这个坑我踩过，别再踩”	ul/li在微信里三大bug
约束规则	硬性限制，不可违反	CSS必须内联、description≤1024字符
辅助文件	长文档放references/子目录	微信HTML限制完整清单

Skill 不能做什么：它不是代码、不是插件、不是API。它是一份结构化文档——Agent 读它、理解它、按它执行，但 Skill 本身不运行任何程序。

文件放在哪

Skill 文件固定叫 SKILL.md，放在：

1

~/.hermes/skills/<分类>/<skill名>/SKILL.md

分类从已有的选，不要自己造：

分类	适合放什么
creative	排版、设计、写作
devops	运维、部署、监控
social-media	公众号、Twitter等平台操作
software-development	代码调试、开发流程
research	论文、调研、数据采集
productivity	文档、表格、PPT

我们的示例：~/.hermes/skills/social-media/wechat-html-formatting/SKILL.md

如果 Skill 内容超过20K字符，可以拆分：

1
2
3
4
5
6


wechat-html-formatting/
├── SKILL.md # 主文件，核心流程
├── references/
│ └── html-constraints.md # 详细限制清单
└── templates/
 └── article-template.html # 完整文章模板

Agent 加载 Skill 时先读 SKILL.md，需要时再读子文件。

这样主文件保持精简，加载速度快，详细内容按需获取。

Frontmatter：写错一个字符就废

SKILL.md 的开头必须是 YAML frontmatter。Agent 靠它识别和索引你的 Skill。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


---
name: wechat-html-formatting
description: 微信公众号文章HTML排版规范。
 包含微信编辑器支持的HTML标签、CSS属性白名单、
 排版最佳实践和常用模板。用于生成公众号草稿时
 确保样式不被过滤。
version: 1.0.0
metadata:
 hermes:
 tags: [wechat, html, formatting]
 related_skills: []
---

硬限制：

字段	限制	不通过的后果
name	≤64字符，小写+连字符	验证失败，Skill不可用
description	≤1024字符	验证失败
整个SKILL.md	≤100,000字符	被截断或拒绝加载
文件开头	必须是`---`（无空行/空格/BOM）	解析失败

只有 name 和 description 是必填的，但建议全填——不填的 Skill 看起来像半成品，也不利于版本管理。

description 决定生死：它不只是简介，更是触发条件。对比一下：

1
2
3
4


❌ "HTML排版工具" —— Agent不知道什么时候加载
❌ "微信公众号相关" —— 太泛，写文章时也会误触发
✅ "用于生成公众号草稿时确保样式不被过滤"
 —— 精准：场景（公众号草稿）+目的（样式不被过滤）

写法公式：“用于[什么场景]时[做什么事]”。

正文结构：4个必写模块

Frontmatter 之后就是正文。结构有套路，参考模板：

模块1：Overview

一两段说清楚做什么、为什么需要。 Agent 通过这段判断"我是不是该用这个Skill"。写得太模糊，Agent 可能跳过你的 Skill。

1
2
3
4


## Overview
微信公众号渲染HTML时会过滤大量标签和样式。
这份Skill汇总了所有已验证的排版规则和模板，
确保生成的HTML在微信客户端正常显示。

模块2：When to Use

显式声明触发场景——什么情况用、什么情况不用。

1
2
3
4


## When to Use
- 把Markdown转成公众号HTML时
- 生成公众号草稿时
- 不要用于：博客发布（博客不需要微信排版规范）

Agent 会拿这段和当前任务对比。写得好就不会误触发。

反面示例：只写"用于公众号"——Agent 在写任何公众号内容时都会触发，包括回复粉丝消息。正面示例：写"用于生成公众号草稿时确保样式不被过滤"——只在排版场景触发。

模块3：核心操作 + 模板

这是Skill最有价值的部分。操作规则必须具体到可以直接执行，模板必须给完整代码。

反面教材：“列表用p标签代替”——Agent会追问：margin多少？字号多少？

正面教材——直接给完整模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 列表项（替代ul/li） -->
<p style="margin:4px 0;line-height:1.8;
 padding-left:14px;">◆ 文字内容</p>

<!-- 代码块（浅灰底） -->
<section style="background:#f6f8fa;padding:12px
 14px;border-radius:6px;margin:8px 0;">
 <p style="margin:0;font-family:monospace;
 font-size:13px;line-height:1.6;color:#333;
 white-space:pre-wrap;">代码内容</p>
</section>

模板越完整，Agent输出越准确，你越省心。

一个好的经验：如果 Agent 用完你的 Skill 后还追加了3个以上问题，说明模板不够细。回去补全。

模块4：Verification Checklist

好的Skill结尾有自检清单。Agent执行完会对照检查——没通过就不交付。

1
2
3
4
5


## Verification Checklist
- [ ] Frontmatter以---开头，无多余空行
- [ ] description描述了具体触发场景
- [ ] 所有模板代码可直接复制使用
- [ ] 踩坑清单覆盖了已知问题

6个坑：关键点+示例

坑1：Frontmatter前有空行

关键点：文件第一个字符必须是---，前面有空行/BOM就解析失败。

1
2


❌ （空行）\n---\nname: xxx
✅ ---\nname: xxx

坑2：description写成口号

关键点：Agent靠description判断是否加载，写得泛=乱触发或不触发。

1
2


❌ "强大的HTML排版工具"
✅ "用于生成公众号草稿时确保样式不被过滤"

坑3：文件超过100K字符

关键点：超限被截断。超过20K就该拆——主文件放流程，细节放references/。

1
2


❌ 一个SKILL.md塞50K内容
✅ SKILL.md(8K) + references/html-constraints.md(30K)

坑4：只写规则不给模板

关键点：“列表用p标签”——Agent不知道margin多少、字号多少。给完整代码。

1
2


❌ "列表用p标签加◆前缀"
✅ '<p style="margin:4px 0;line-height:1.8;padding-left:14px;">◆ 内容</p>'

坑5：写完以为立刻生效

关键点：Skill在会话启动时加载。新写的Skill要新开会话才能看到。

1
2


❌ 写完Skill → 同一会话测试 → "怎么找不到"
✅ 写完Skill → 新开会话 → 自动加载

坑6：没写When to Use

关键点：Agent不知道什么时候该用这个Skill。触发场景写清楚，正反面都要写。

1
2


❌ 没有When to Use → Agent乱猜
✅ 明确"用于公众号草稿"+"不要用于博客"

写在最后

Skill 不是写一次就完的文档。每次Agent执行出错、每次发现新坑，都是更新的时机。

我那个md转html的Skill，从初版到现在改了7次——微信渲染的坑远比想象中多。但它现在稳了：Agent加载后，生成的HTML零调试直接能用。

写 Skill 的最佳节奏：用一次，改一次。别想着一次写完美。先跑通最简版本，然后在实战中逐步补全模板和踩坑清单。 3次迭代后的 Skill，远比一次性憋出来的"完美版"更实用。

教程 on Kalend's Blog