Agent Skills 使用体验：把经验写成一个文件夹

用编程 Agent 久了会发现一个规律：它能力够，但不知道你的规矩。每次让它发一篇笔记，都要重新交代一遍“文件放哪、frontmatter 怎么写、写完跑一下构建”。说漏一条，它就按自己的理解来。

Agent Skills 就是用来解决这个问题的：把一类任务的做法写成一个文件夹，Agent 在需要的时候自己去读。

Skill 长什么样

一个 Skill 就是一个目录，核心是里面的 SKILL.md：

write-note/
├── SKILL.md          # 必需：元信息 + 操作说明
├── reference.md      # 可选：详细规范，需要时再读
└── scripts/
    └── check.mjs     # 可选：可直接执行的脚本

SKILL.md 开头是一段 YAML 元信息，必填两个字段：

---
name: write-note
description: 为 cube007.cn 博客撰写并发布笔记。当用户要求写文章、发笔记、新增博客内容时使用。
---

# 写笔记

1. 在 `src/content/notes/` 下新建 `<英文短横线文件名>.md`，文件名即 URL
2. frontmatter 必须包含 title、date、tags、description；tags 优先复用已有标签
3. 正文用 `##` 作为一级小节，不要用 `#`
4. 多篇一起写时，date 之间要间隔几天
5. 写完运行 `npm run build`，确认没有报错再汇报

name 只能用小写字母、数字和连字符，description 说明它做什么、什么时候用。放进工具约定的 skills 目录（项目级或用户级，各家路径略有不同），就生效了。

这套格式最早由 Anthropic 提出，后来作为开放标准被不少编程 Agent 采纳，同一个 Skill 文件夹基本可以在不同工具之间通用。

关键设计：渐进式加载

Skill 最聪明的地方在于按需加载，分三层：

1. 启动时：Agent 只看到每个 Skill 的 name 和 description，每个也就几十个 token。装几十个 Skill 都不心疼
2. 判断相关时：Agent 根据任务和 description 匹配，觉得有用才去读 SKILL.md 正文
3. 执行中：正文里提到“详细规范见 reference.md”，它需要时才去打开；scripts/ 里的脚本可以直接运行，代码本身都不用进上下文

对比一下把所有规范都塞进系统提示词：不管当前任务用不用得上，每轮对话都要背着这几千 token 走。Skill 把“知道有这么个东西”和“知道具体怎么做”拆开了。

和 Rules、MCP 的区别

刚接触时最容易混的是这三个，用一段时间后我的理解是：

	什么时候生效	提供什么	适合放什么
Rules / AGENTS.md	每次对话都在上下文里	约束和背景	项目必须时刻遵守的规矩：技术栈、目录约定、禁止事项
Skills	任务相关时才加载	做法（流程和知识）	某类任务的具体步骤：发笔记、写测试、做代码审查
MCP	接上后工具一直可用	能力（能调用的工具）	访问外部系统：数据库、浏览器、GitHub

一个粗暴的判断方法：每次都要遵守的写 Rule；某类任务才用到的写 Skill；Agent 本来做不到、需要新能力的接 MCP。 三者经常组合使用 —— 比如一个“发布版本”的 Skill，里面的步骤会调用 GitHub 的 MCP 工具。

用下来的写法经验

description 是触发器，最值得花时间。 Agent 只凭 description 决定用不用，写成“博客相关”太含糊，不会触发；写成“当用户要求写文章、发笔记、新增博客内容时使用”就准多了。把用户可能的说法写进去。

正文写成步骤清单，不要写成散文。 Agent 照着清单执行的稳定性远高于从一段描述里提炼要点。每一步用祈使句，具体到命令和路径。

SKILL.md 保持短小。 正文我一般控制在一两百行内，长的规范、示例、API 文档拆进单独的文件，在正文里写清楚“什么情况下去读哪个文件”。

确定性的步骤交给脚本。 校验 frontmatter 格式、生成目录结构这类事，让模型每次手写不如给它一个脚本跑。脚本不会“理解偏”，还省 token。

一定要写验证步骤。 最后一步永远是“运行 xxx 确认结果”。没有这一步，Agent 很容易写完就宣布大功告成。

从真实的纠正里提炼。 我写 Skill 最好的素材，是那些“我第三次纠正它同一个问题”的时刻。与其每次口头提醒，不如把这条写进 Skill 里，一劳永逸。

别装太多功能重叠的 Skill。 两个 Skill 的 description 都声称处理“代码审查”，Agent 会犹豫选哪个，有时两个都不选。定期清理，让每个 Skill 的触发范围清晰不重叠。

没触发就直接点名。 判断失误时，在对话里直接说“用 write-note 这个 skill”，比改一堆描述来得快。如果某个 Skill 总要点名才触发，说明它的 description 该改了。

社区 Skill 值得装吗

值得，但要看一眼内容。社区里有不少好用的：强制先写测试的 TDD 流程、按固定维度做代码审查、生成架构图的。它们本质上是别人沉淀下来的工作方法，装一个等于请了一位有固定习惯的同事。

但 Skill 能让 Agent 执行脚本、调用工具，装来路不明的 Skill 和运行来路不明的代码没区别。装之前读一遍 SKILL.md 和 scripts/，花不了几分钟。

一句话：Rules 告诉 Agent “要守什么规矩”，MCP 给它“能用的工具”，Skills 教它“这类事具体怎么做”。最好的 Skill，来自你反复纠正它的那些瞬间。