如果你刚开始接触 Agent 开发，你很可能听过「Skill」这个词。但你可能也和我当初一样，把它当成「一段写得更认真的提示词」——往文件夹里一丢，就觉得自己整挺明白。

这个理解不丢人，但它是错的。

Skill 不是一个更长的 prompt。它是你 Agent 运行时架构中的一个 可部署模块——有自己的加载时机、执行顺序、成功标准和反馈回路。

一、Skill 的本质：模块，不是文档

你不会把所有代码塞进一个 main 函数——你会拆成模块，每个模块管一件事，有明确的输入输出。

Skill 就是这个思路在 Agent 世界的映射。

Agent 有多个层次：Memory 记住偏好，CLAUDE.md 定义项目级默认行为，Hook 强制执行关键约束。而 Skill 解决的是——按需加载的专题工作流。只在特定任务触发，不占常驻 token。

二、Skill 的结构：五个关键部分

一个完整的 Skill 包含五部分：

1. description — 触发的钥匙。 Agent 依此判断何时加载。好的写法：「发版前的完整流程——当用户说发版、release 时触发」。坏的写法：「发版流程」。

2. 前置条件 — 告诉 Agent 第一步检查什么。 环境变量、工具安装、文件路径——Agent 不会主动检查的，写进 Skill。

3. 步骤 — 可执行的指令序列。 每步一个动作。不写「优化代码」，写「运行 lint → 修复 error → 重新运行直到通过」。

4. 验证 — 怎么知道做对了。 每步设 checkpoint：「测试全部通过」「lint 0 error」「文件已生成」。Agent 不会自己知道「做对了」。

5. 陷阱 — 提前标注已知的坑。 这节价值被严重低估。每个踩过的坑都写下来——Agent 会读。

四个核心原则：

原则一：线性优于分支。 A→B→C→D 胜过「如果 X 做 A，如果 Y 做 B」。需要分支时用关键词路由，别让 Agent 自己判断。

原则二：每步可独立验证。 不写「部署」，写「运行 migrate → 检查无 ERROR → 运行 check → 确认 OK → 部署」。

原则三：脚本优于自然语言。 把 API 调用包成脚本——Skill 负责决策，脚本负责执行。

原则四：内置「自救」路径。 每步加失败处理：「如 package.json 不存在，检查目录」「API 返回 401，检查 API_KEY」。

反馈循环：用 → 发现问题 → 修 → 沉淀经验 → 再用

每次 Agent 执行完 Skill，做两件事：

1. 看执行日志——有没有跳过步骤？卡住反复重试？读不存在的文件继续执行？

2. 问自己——这次学到的东西该进 Skill 的哪个部分？步骤不够具体？前置条件漏了？陷阱没标？

实用检查清单：

✅ description 是否准确描述触发条件？
✅ 每一步是否可独立验证？
✅ 失败时 Agent 是否有逃生路径？
✅ 是否区分了「Skill 决策」和「脚本执行」？
✅ 最近一次的问题是否已写进陷阱？

陷阱 1：description 太宽泛。 「处理所有数据库操作」→ 改成「数据库迁移：创建/修改表结构时触发」。

陷阱 2：把 Skill 当文档。 「我们用 PostgreSQL」→ CLAUDE.md。「连接并检查所有表」→ Skill。记住：事实常驻，流程按需。

陷阱 3：步骤太密。 一步塞 5 个动作，Agent 容易偏离。拆开，每步一个动作。

陷阱 4：没有「完成标准」。 Agent 不知道何时算做完。明确告诉它：「curl 返回 200 且 status=ok 时，此步骤完成。」

Skill 不是什么高深概念。拆开看，就是一个给 AI 看的操作手册——关键是你用什么心态写它。

当「一段话」写，Agent 靠猜。当「一个模块」写——有接口、前置条件、步骤、验证——Agent 就像训练有素的工程团队。

最好的 Skill 不是一次写完美的。是每次跑完顺手改一行的。改着改着，它就变成你 Agent 操作系统里最可靠的零件。

开始写你的第一个 Skill 吧。写出来、跑一次、修一次，下一行怎么写你就知道了。