Agent Skills 与可复用能力

日期：2026-06-10

一、直觉

如果 Prompt 是“临时交代一件事”，Skill 就是“把一套可重复的工作方法写成说明书，放到 agent 的工具箱里”。

你可以把 Skill 理解成：

可复用 prompt + 工作流程 + 参考资料 + 可选脚本 + 触发说明

它不是让模型变得无所不能，而是把你已经验证过的做事方法沉淀下来，让 agent 在合适的时候自动加载。

本讲常见术语先按下面理解，详细定义和更多例子见 00.5-术语词典与最小用例。

二、Skill 解决什么问题

1. 减少重复提示

你不用每次都复制一大段要求，例如：

• 代码审查标准。
• 论文阅读流程。
• 数据分析步骤。
• UI 设计规范。
• 周报格式。
• 项目测试命令。

2. 降低上下文成本

现代 Skills 使用 progressive disclosure：

只先加载 name + description
任务匹配时再加载 SKILL.md
需要时再读取 references / scripts / assets

这样可以安装很多技能，但不让每个技能都挤进上下文。

3. 固化经验

很多经验不是模型不知道，而是模型不会默认按你的方式做。Skill 可以固化：

• 团队偏好。
• 项目约定。
• 特定工具链。
• 容易踩坑的边界。
• 成功案例中的固定流程。

4. 让能力可版本化

Skill 是文件和目录，能被 Git 管理。你可以记录：

• 为什么改。
• 改了什么。
• 哪些测试样例通过。
• 哪些失败样例仍然存在。

三、Skill 的基本结构

一个标准 Skill 目录通常长这样：

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/

1. SKILL.md

必须有 YAML frontmatter：

---
name: prompt-reviewer
description: Use this skill when the user wants to review, debug, or improve a reusable prompt, system instruction, AGENTS.md, or Agent Skill. Focus on task clarity, trigger scope, output format, evaluation, and safety.
---

# Prompt Reviewer

Follow this workflow...

name 用来标识技能，description 用来决定什么时候触发。

2. scripts/

放可执行脚本。适合确定性任务：

• 校验 JSON。
• 转换格式。
• 跑测试。
• 抽取字段。
• 生成报告。

注意：

• 脚本要非交互。
• 参数清楚。
• 错误信息可操作。
• 输出尽量结构化。

3. references/

放详细参考资料。适合：

• 长规范。
• API 说明。
• 团队文档。
• 评分标准。
• 复杂边界案例。

主 SKILL.md 不要塞太长。它只应该告诉 agent 什么时候读哪份参考。

4. assets/

放模板和静态资源：

• 文档模板。
• 表格模板。
• 示例文件。
• 图片资源。
• 配置片段。

四、Skill 的触发核心：description

Skill 是否会被正确调用，很大程度取决于 description。

坏描述：

description: Helps with prompts.

问题：

• 太泛。
• 不说明什么时候用。
• 容易误触发，也容易漏触发。

好描述：

description: Use this skill when the user wants to create, review, debug, or optimize reusable prompts, system instructions, AGENTS.md files, or Agent Skills. Apply it to improve task clarity, trigger scope, output format, evaluation coverage, and prompt-injection resistance.

好在哪里：

• 用 “Use this skill when...” 直接告诉 agent 触发条件。
• 覆盖用户意图，而不是只写内部实现。
• 列出边界：prompt、system instructions、AGENTS.md、Agent Skills。
• 明确输出价值：clarity、scope、format、evaluation、safety。

五、写 Skill 的流程

第一步：从真实任务提取

不要凭空写一个泛泛的 Skill。先完成 2-3 次真实任务，总结：

• 哪些步骤总是有效。
• 哪些地方经常需要纠正。
• 输入一般长什么样。
• 输出应该长什么样。
• 哪些工具或脚本稳定有用。

第二步：写最小 SKILL.md

先写核心工作流，不要一次性写百科全书。

推荐结构：

---
name: skill-name
description: Use this skill when...
---

# Purpose

这个 skill 解决什么问题。

# When To Use

什么时候使用。

# Workflow

1. ...
2. ...
3. ...

# Output

输出格式。

# Common Mistakes

容易出错的地方。

# References

需要时读取哪些文件。

第三步：做触发测试

准备两类测试 query：

• should trigger：应该触发。
• should not trigger：不应该触发。

例如 prompt-reviewer：

[
  {
    "query": "帮我优化这份系统提示词，让输出更稳定",
    "should_trigger": true
  },
  {
    "query": "帮我写一篇关于提示词工程的作文",
    "should_trigger": false
  }
]

目标是减少两种错误：

• 漏触发：该用 Skill 时没用。
• 误触发：不该用 Skill 时用了。

第四步：做输出质量评估

触发正确不等于效果好。还要测试：

• 是否按流程做。
• 是否减少常见错误。
• 是否比不用 Skill 更好。
• 是否节省用户说明成本。
• 是否带来新问题。

第五步：迭代

每次只改一个主要问题：

• 修改 description。
• 精简正文。
• 增加边界案例。
• 移动长内容到 references。
• 增加脚本。
• 增加输出检查。

六、Skill 写作原则

1. 只写模型容易漏掉的东西

不要浪费上下文解释常识。

差：

Markdown 是一种轻量级标记语言。

好：

本项目的 Markdown 文件标题只使用中文，代码块必须带语言标识。

2. 写过程，不只写原则

差：

请高质量地审查提示词。

好：

先判断任务类型，再检查输入边界、输出格式、失败样例、评估方式和安全边界。

3. 给默认路径，不给太多菜单

模型遇到太多选项会犹豫或乱选。Skill 应该给一条默认有效路径，再说明例外情况。

4. 让大型 Skill 分层加载

如果内容很长：

• SKILL.md 放核心流程。
• references/ 放详细规则。
• scripts/ 放稳定操作。
• assets/ 放模板。

5. 脚本承担确定性，模型承担判断

适合脚本：

• 校验格式。
• 提取固定字段。
• 排序统计。
• 跑测试。

适合模型：

• 解释原因。
• 归纳模式。
• 处理歧义。
• 写自然语言。

七、平台边界：Skill、Prompt、AGENTS.md、Memory、MCP 的区别

这里的 Skill、Plugin、AGENTS.md、Subagent 等概念偏 Codex / Agent 平台生态；不同产品可能叫法不同，也可能只支持其中一部分。学习时重点掌握背后的通用问题：复用流程放哪里、项目规则放哪里、外部数据怎么接入、权限和评估怎么做。

八、一个学习用 Skill 示例

---
name: prompt-engineering-tutor
description: Use this skill when the user is learning prompt engineering, context engineering, agent skills, RAG, structured outputs, tool use, or prompt evaluation. Teach with intuition, formal structure, examples, misconceptions, checks, and next steps.
---

# Prompt Engineering Tutor

## Workflow

1. Identify the learner's current topic and level.
2. Explain the intuition first.
3. Give the formal concept.
4. Show a small example.
5. Name one common misconception.
6. Ask 2-5 understanding-check questions.
7. Suggest the next lesson or exercise.

## Boundaries

- Do not over-focus on one domain unless the user asks.
- Prefer reusable mental models over one-off prompt tricks.
- When teaching recent tooling such as Skills, MCP, or structured outputs, verify official docs first.

九、常见误区

误区 1：把所有提示词都做成 Skill

不需要。Skill 适合复用和流程化，不适合一次性小问题。

误区 2：Skill 越详细越好

不一定。Skill 太长会污染上下文。应该只保留高信号流程。

误区 3：description 随便写

description 是触发入口。写不好，Skill 就等于不存在。

误区 4：Skill 可以替代工具

不能。Skill 是指导 agent 怎么做；工具和脚本才真正执行确定性动作。

误区 5：Skill 可以替代评估

不能。Skill 是否有效，要靠触发测试和输出质量测试。

十、理解检查

1. Skill 和普通 prompt 最大区别是什么？
2. 为什么 Skill 的 description 特别重要？
3. 什么内容适合放 SKILL.md，什么内容适合放 references/？
4. 为什么脚本应该承担确定性工作？
5. 一个提示词什么时候应该升级成 Skill？

十一、练习

设计一个你自己的 Skill：

名称：
目标：
什么时候触发：
什么时候不触发：
核心流程：
输出格式：
常见错误：
需要的参考资料或脚本：

下一次可以把这个草案发给 AI，让它帮你优化成标准 SKILL.md。