从零到一：如何为你的 AI Agent 编写一个好用的 SKILL

一套真正好用的 Agent，靠的往往不是某个万能的"超级提示词"，而是一个个被精心打磨过的 SKILL。本文从实战出发，带你把一个想法变成一个可以反复复用、能被别人继承的能力模块。

一、为什么你需要写自己的 SKILL

在过去，我们和 AI 打交道的方式是"一问一答"：把需求说清楚，等它回应。这种方式有两个天然的瓶颈：

1. 上下文越来越重。 每次重复解释同样的背景、同样的格式要求、同样的工具用法，既浪费 token，也容易让模型跑偏。
2. 经验无法沉淀。 今天调好的一套流程，明天换个会话就得从头再来。

SKILL 的思路正好反过来：把"怎么做某件事"沉淀成一个可复用的能力单元。当任务命中某个 SKILL 时，Agent 只需加载对应的小段说明，就能以稳定、一致的方式完成任务。它本质上是一种"给 AI 用的说明书"。

换句话说，SKILL 是给经验打包，让能力可复用、可传递、可组合。

二、SKILL 到底是什么

一个 SKILL，通常就是一个文件夹 + 一个 SKILL.md 文件：

my-skill/
├── SKILL.md          # 核心说明（必需）
├── references/       # 参考资料（可选）
├── examples/         # 示例（可选）
└── scripts/          # 辅助脚本（可选）

其中 SKILL.md 是整个 SKILL 的"门面"，它一般包含两部分：

• Frontmatter（头部元信息）：用 --- 包裹的 YAML，声明这个 SKILL 叫什么、什么时候该用。
• 正文（Body）：具体的操作指引、规则、流程、注意事项。

一个最简的 SKILL.md 长这样：

---
name: weekly-report
description: 当你需要把一周的工作整理成结构化周报时使用此技能。
---

# 周报生成

## 适用场景
- 用户说"写周报""整理本周工作"
- 每周五下午的固定汇报

## 执行步骤
1. 先收集本周完成的事项
2. 按"成果 / 进展 / 问题 / 下周计划"四段式组织
3. 语言精炼，每条不超过 20 字

## 输出格式
使用 Markdown，一级标题为周报标题，正文用无序列表。

三、写 SKILL 的核心心法

1. 先想清楚"什么时候该用它"

SKILL 最关键的部分，其实是那句 description。因为 Agent 在决定"要不要加载这个 SKILL"时，靠的就是它。

描述要回答两个问题：它解决什么问题？什么时候该触发？ 写得太泛，会被滥用；写得太窄，又永远触发不了。

对比一下：

# ❌ 太泛，什么都能套
description: 用于处理各种文档。

# ✅ 有明确的触发条件
description: 当用户需要把 Word 文档批量转换成 PDF，或需要检查 PDF 格式时使用。

2. 只写"AI 不知道的东西"

这是最容易踩的坑。很多人一上来就把"什么是 Python""什么是 Markdown"全写进去，这完全是浪费。AI 本身已经具备这些常识。

真正有价值的是那些只有你知道、或需要特定流程才能做对的信息：

• 你的团队/项目特有的命名规范
• 某一步操作的先后顺序不能乱
• 容易出错的边界情况
• 特定工具在你的环境里怎么调用
• 输出必须遵守的格式或红线

3. 让指令"可执行"，而不是"讲道理"

不要写"请认真完成""请仔细检查"这类空话。要写成具体的、可检查的动作。

# ❌ 空话
请仔细检查文档有没有错误。

# ✅ 具体动作
检查以下三项，并在回复中逐条列出结果：
1. 所有超链接是否可访问（用 HEAD 请求验证）
2. 图片是否都引用了正确的相对路径
3. 目录页码与正文标题是否一一对应

4. 一次只讲一件事

一个 SKILL 解决一个问题。如果一个 SKILL 里塞进了"写周报 + 发邮件 + 做表格"，那它很快会变成一锅粥，模型不知道该先做哪个。

正确的做法是拆分：把大流程拆成多个小 SKILL，彼此之间用清晰的触发条件区分。小而专的 SKILL，远比大而全的 SKILL 好用。

5. 提供"参考文件"来分担上下文

如果某个 SKILL 的正文很长，不要全部塞在 SKILL.md 里。可以这样做：

• SKILL.md 只放主流程和关键规则
• 把详细细节放到 references/ 目录
• 正文里写一句"更完整的规范见 references/xxx.md"

这样 Agent 平时只加载轻量的主说明，只有真正需要细节时才去读参考资料。这叫做渐进式披露（Progressive Disclosure），是管理上下文的有效手段。

四、一个完整的实战例子

假设你要做一个"代码评审助手"的 SKILL。我们可以这样设计：

code-review/
├── SKILL.md
└── references/
    └── checklist.md

SKILL.md：

---
name: code-review
description: 当用户提交代码变更、请求审查，或提到"帮我看看这段代码"时使用此技能。
---

# 代码评审

## 何时使用
- 用户提交了 diff / PR
- 用户请求代码审查
- 用户说"帮我看看这段代码"

## 评审原则
1. 先看整体设计，再看局部实现，最后看风格
2. 每个问题必须说明：位置、原因、建议改法
3. 区分「必须修改」和「建议改进」

## 检查清单
按以下顺序检查（详见 references/checklist.md）：
1. 是否有明显的逻辑错误或边界条件遗漏
2. 是否存在安全风险（注入、越权、敏感信息）
3. 命名与注释是否清晰
4. 是否有重复代码可抽取

## 输出要求
- 使用中文
- 每条问题格式：`【严重程度】文件:行号 - 问题 - 建议`
- 最后给出一句话总体评价

references/checklist.md：

# 详细检查清单

## 安全
- SQL 是否使用参数化查询
- 用户输入是否做了校验
- 敏感配置是否硬编码

## 健壮性
- 空值 / 超长 / 异常输入是否处理
- 资源（文件、连接）是否正确释放
- 是否有未捕获的异常

## 可维护性
- 函数长度是否超过 50 行
- 是否存在魔法数字
- 注释与代码是否一致

这样拆分之后，主说明保持简洁，细节可以随时扩展，而且评审规则可以独立更新而不影响主流程。

五、写好 SKILL 的检查清单

在发布你的 SKILL 之前，不妨对照下面这份清单过一遍：

•  触发条件清晰：别人一看 description 就知道什么时候该用
•  不写常识：只包含 AI 需要你告诉它的内容
•  指令可执行：每条都是具体动作，而非抽象口号
•  范围单一：一个 SKILL 只解决一类问题
•  结构分明：主说明简洁，细节下沉到参考文件
•  有示例：关键步骤附上输入输出示例
•  边界明确：写清楚"不适用于什么情况"
•  持续迭代：根据实际使用反馈不断修订

六、几个常见误区

误区一：SKILL 写得越长越好。 恰恰相反。冗长、重复的说明会稀释关键信息，让模型抓不住重点。好的 SKILL 是"精炼"的。

误区二：把所有工具用法都塞进 SKILL。 工具用法属于通用知识，只有当你的环境有特定限制时才需要写。否则就是噪音。

误区三：忽略"不适用"的情况。 明确写出什么情况不该用这个 SKILL，可以避免误触发，这和写触发条件同样重要。

误区四：写完就不管了。 SKILL 是需要维护的。随着工具、流程变化，它的内容也要跟着更新，否则会逐渐失效。

七、小结

写 SKILL 的本质，是把"怎么做一件事"这件事本身，变成一件可复用、可传递、可优化的资产。它不需要多复杂，关键是：

1. 触发条件准确
2. 内容精炼实用
3. 结构清晰，细节下沉
4. 持续迭代

当你开始为重复性的任务写 SKILL 时，你其实是在为 AI 建立一套"肌肉记忆"。一开始可能只是几个小文件，但随着积累，它会逐渐长成一个真正属于你自己的能力库。

从今天起，试着为你最常重复的一件事，写第一个 SKILL 吧。