Skills 理论知识教程

1. Skill 到底是什么

这是一份面向 Codex/Agent Skills 的理论教程，重点解释：

• Skill 到底是什么
• 它为什么存在
• 它和普通提示词、脚本、知识库之间的区别
• 一个好 Skill 背后的设计原则是什么
• 为什么有些 Skill 很稳定，而有些 Skill 写了等于没写

2. 什么是 Skill

Skill 可以理解为一种面向 AI 代理的“可复用任务模块”。
它不是单次对话里的临时提示，而是一套可以长期复用的专业化工作说明。

一个 Skill 通常会把下面几类信息组织在一起：

• 某类任务的适用范围
• 该任务推荐的执行流程
• 需要遵守的规则和限制
• 需要读取的参考资料
• 需要运行的脚本或模板资源

它的目标不是“告诉模型所有知识”，而是让模型在遇到某类任务时，能快速进入一个更专业、更稳定、更省上下文的工作模式。

3. Skill 的本质

从本质上看，Skill 做的是三件事：

3.1 把零散经验变成结构化流程

很多重复任务之所以效率低，不是因为模型不会，而是因为每次都要重新理解一遍：

• 这次任务属于什么类型
• 应该先做什么，再做什么
• 哪些规则必须遵守
• 哪些文件要读
• 哪些步骤要验证

Skill 的作用，就是把这些“隐性经验”变成“显性流程”。

3.2 把不稳定输出变成更稳定的执行模式

如果一个任务只靠自然语言描述，模型每次都可能走不同路线。
这在探索型任务里是优点，但在重复型、脆弱型、依赖上下游格式的任务里就是缺点。

Skill 通过预先定义：

• 触发条件
• 执行顺序
• 可选资源
• 失败时的处理方式

来降低这种随机性。

3.3 把大块知识按需加载，而不是一次性塞进上下文

一个成熟 Skill 并不追求把所有资料都写进 SKILL.md。
更合理的方式是：

• 元数据负责触发
• SKILL.md 负责核心流程
• references/ 负责详细知识
• scripts/ 负责确定性操作
• assets/ 负责最终产物所需资源

这就是 Skill 的核心思想之一：按需加载，而不是一次性灌满上下文。

4. Skill 是怎么工作的

理解 Skill，最重要的是理解它的加载模型。

4.1 三层加载机制

Skill 一般可以分成三层：

1. 元数据层
   主要是 name 和 description。
   这是最先被看到的部分，用于判断“这个 Skill 是否应该被触发”。

2. 主体说明层
   也就是 SKILL.md 的正文。
   只有在 Skill 被判断为相关时，正文才会被真正使用。

3. 附加资源层
   包括 references/、scripts/、assets/。
   这些资源通常只在执行过程中按需读取，不会一开始全部塞进上下文。

4.2 一个简化的工作链路

可以把 Skill 的触发过程理解成下面这条链路：

用户请求 -> 匹配 description -> 触发 Skill -> 读取 SKILL.md -> 按需读取 references/scripts/assets -> 执行 -> 验证

这意味着，真正决定 Skill 能不能被正确用上的，首先不是正文，而是 description。

5. 为什么 Skill 不是普通提示词

很多人第一次接触 Skill，会把它理解成“一个高级 prompt”。
这只对了一半。

两者的区别在于复用方式和组织方式。

维度	普通提示词	Skill
生命周期	通常只服务当前对话	可以长期复用
触发方式	需要手动输入	依赖元数据和场景触发
内容组织	常常混在一段文字里	结构化拆分为流程、规则、资源
上下文成本	每次都要重贴	核心信息按需加载
扩展方式	越写越长	可以拆分 references/scripts/assets
稳定性	依赖临场表述质量	更适合沉淀固定流程

所以 Skill 的关键不是“提示词更长”，而是“把任务经验做成模块化工作单元”。

6. Skill 和脚本、知识库、MCP 的区别

6.1 Skill 不是脚本

脚本负责执行确定性逻辑，比如：

• 清洗 JSON
• 批量改名
• 调接口
• 转换格式

Skill 负责告诉代理：

• 什么时候要运行脚本
• 用哪个脚本
• 运行前后要检查什么
• 当脚本不够时，剩下的判断怎么做

总结：脚本是执行器，Skill 是任务编排器。

6.2 Skill 不是知识库

知识库的重点是“存内容”，比如制度、接口文档、字段定义。
Skill 的重点是“指导行动”，告诉代理这些知识在什么时机、按什么方式使用。

总结：知识库回答“知道什么”，Skill 回答“怎么做”。

6.3 Skill 不是 MCP

MCP 或其他工具接口，解决的是“能做什么操作”。
Skill 解决的是“面对这个任务时，应该怎样组织这些操作”。

一句话总结：MCP 提供手，Skill 提供方法。

7. 什么情况下应该写 Skill

适合写成 Skill 的场景通常有这些特征：

• 任务反复出现
• 执行步骤相对固定
• 有明确规则或约束
• 对输出稳定性有要求
• 需要结合本地文档、脚本、模板或业务知识
• 新人或新会话进入时，重复解释成本很高

典型场景包括：

• 网站采集流程
• 自动化测试录制与回放
• 某类报表生成
• 代码库中的固定排查流程
• 某一类异常的标准诊断路径
• 某公司内部的交付规范

8. 什么情况下不应该写 Skill

以下情况一般不值得做成 Skill：

• 只会做一次的任务
• 任务边界非常模糊，且每次变化都很大
• 只是想存一份通用知识介绍
• 任务本身完全可以靠一个脚本解决
• 你还没有形成最基本的工作流，就急着抽象

如果一个流程还处在频繁变化、没有稳定模式的早期阶段，先用普通提示和实验记录更合适。
当模式开始稳定时，再抽象成 Skill，成本和收益会更匹配。

9. Skill 设计的核心理论

这一部分是写好 Skill 的关键。

9.1 上下文预算理论

上下文不是无限资源。
Skill 和系统提示、对话历史、用户请求、代码片段都在竞争同一个上下文窗口。

因此，Skill 设计的第一原则不是“越全越好”，而是：

只放模型真正需要、且无法从通用能力中自然补足的内容。

这意味着你应该删除这些东西：

• 教科书式常识
• 大量废话式背景说明
• 与任务无关的介绍
• 重复写在多处的同一段规则

9.2 渐进式披露理论

好的 Skill 不是把所有细节堆在一个文件里，而是采用分层结构：

• 在 description 中定义触发边界
• 在 SKILL.md 中写核心流程
• 在 references/ 中存放大段资料
• 在 scripts/ 中封装确定性动作

这样做的好处有两个：

• 减少无关信息进入上下文
• 让 Skill 更容易维护和扩展

9.3 自由度控制理论

不同任务需要不同“自由度”。

高自由度

适合下面这类任务：

• 允许多种解法
• 需要根据上下文灵活选择策略
• 更偏分析、诊断、创作

这时 Skill 应该提供：

• 判断原则
• 决策启发
• 风险提示

而不是写死每一步。

中等自由度

适合下面这类任务：

• 有推荐路径，但允许局部变化
• 需要一定灵活度
• 执行模式大体稳定

这时 Skill 应该提供：

• 推荐流程
• 关键检查点
• 常见分支处理

低自由度

适合下面这类任务：

• 容错率低
• 格式要求严格
• 步骤顺序固定
• 频繁重复执行

这时 Skill 应该：

• 指定明确顺序
• 指定固定脚本或命令
• 限制随意发挥空间

一句话总结：流程越脆弱，Skill 给出的护栏就应该越多。

9.4 确定性与启发式的分工

Skill 设计时要始终问自己一个问题：

这一步到底应该交给模型判断，还是交给脚本处理？

一般来说：

• 可计算、可校验、格式明确的步骤，优先交给脚本
• 需要语义判断、策略决策、上下文理解的步骤，保留给模型

例如：

• “把 JSON 字段名转成 snake_case” 适合脚本
• “判断文章标题是否带明显营销倾向” 更适合模型

9.5 验证完整性理论

Skill 不是写完就结束。
一个可用 Skill 必须包含验证思路。

至少要能回答：

• 触发是否准确
• 输出是否稳定
• 错误时是否容易定位
• 新样本是否还能适用

因此，成熟 Skill 通常会明确：

• 如何回放
• 如何检查结果
• 哪些症状说明 Skill 设计有问题

10. 一个 Skill 的标准结构

最常见的结构如下：

my-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── guide.md
│   └── schema.md
├── scripts/
│   └── normalize.py
└── assets/
    └── template.md

10.1 SKILL.md 是核心

这是唯一必需文件。
没有它，就不能称为一个完整 Skill。

它一般包含两部分：

1. YAML Frontmatter
   主要是 name 和 description

2. Markdown 正文
   主要是流程、规则、资源指引

10.2 agents/openai.yaml 的作用

这个文件通常用于 UI 元数据展示，例如：

• 展示名称
• 简介
• 默认提示

它不是所有场景都必须有，但在需要把 Skill 暴露给界面或列表时很有用。

10.3 references/ 的作用

这个目录存放详细说明，不建议把这类内容全部写在 SKILL.md：

• 字段定义
• 接口文档
• 业务规则
• 复杂示例
• 某个平台的专项说明

10.4 scripts/ 的作用

这个目录适合放需要重复执行、且追求稳定的工具脚本，例如：

• 结果后处理
• 数据格式转换
• 文件清洗
• 验证器

10.5 assets/ 的作用

这个目录适合放产物相关资源，例如：

• 报告模板
• 输出骨架
• 示例配置
• 图片、字体、静态片段

11. SKILL.md 里最关键的两个字段

11.1 name

name 应该简洁、稳定、明确。
它更像一个模块名，不是营销标题。

推荐特点：

• 短
• 清晰
• 不玩花样
• 尽量体现任务域

例如：

• mcp-web-test-recorder
• crawl-output-postprocess
• seo-density-auditor

11.2 description

description 是触发的关键。
它应该明确回答：

• 这个 Skill 干什么
• 在什么情况下使用
• 用户可能会怎么描述这类需求

好的 description 通常会包含：

• 动作词
• 任务名词
• 场景词
• “Use when …” 这一类触发语义

一个过于模糊的例子：

description: Help with websites.

问题很明显：

• 范围过大
• 没有动作
• 没有边界
• 几乎无法判断什么时候该触发

一个更好的例子：

description: Post-process crawler output into clean Markdown or normalized JSON, especially when raw extraction is incomplete, HTML is noisy, or links and metadata need cleanup. Use when asked to clean, normalize, enrich, or repair crawl results.

这个描述做对了几件事：

• 明确任务类型
• 明确输入问题
• 明确输出方向
• 明确触发词

12. SKILL.md 正文应该写什么

正文不需要面面俱到，但要覆盖最核心的动作逻辑。
一个常见结构是：

12.1 Overview

说明这个 Skill 的目标、范围和定位。

12.2 Workflow

给出推荐工作流。
这部分是正文的核心。

12.3 Rules

列出必须遵守的约束，例如：

• 先检查再执行
• 优先用稳定选择器
• 不要把敏感信息写死
• 输出必须保留原字段

12.4 Resources

告诉代理：

• 什么时候去读 references/
• 什么时候去跑 scripts/
• 什么时候要用 assets/

13. 理论上，好的 Skill 长什么样

一个好的 Skill 通常具备这些特征：

• 触发边界明确
• SKILL.md 不臃肿
• 参考资料有拆分
• 需要稳定性的地方用脚本托底
• 工作流清楚
• 有校验思路
• 容易维护

反过来，一个差 Skill 常常具备这些问题：

• 什么都想管
• 文档很长但没有结构
• description 极其模糊
• 细节全堆在 SKILL.md
• 没有验证步骤
• 没有边界，导致误触发或不触发

14. 常见反模式

14.1 把 Skill 写成 README

这是最常见的错误之一。
README 是给人看的，Skill 是给代理执行任务用的。

如果文档里充满：

• 项目背景
• 设计故事
• 安装说明
• 冗长术语解释

那通常说明写偏了。

14.2 把所有东西都塞进 SKILL.md

短期看起来方便，长期一定难维护。
更严重的是，会占用大量上下文。

14.3 没有触发边界

如果 description 太泛，Skill 会：

• 到处误触发
• 或者根本触发不到正确任务

14.4 该写脚本的地方全靠模型硬猜

这会导致输出不稳定。
凡是可以明确计算、转换、校验的事情，都应该考虑脚本化。

14.5 参考资料层层跳转

如果 SKILL.md 指向 A，A 又指向 B，B 再指向 C，代理很容易迷路。
更好的做法是让 SKILL.md 直接指向关键参考文件。

15. 如何评价一个 Skill 是否合格

可以用下面这组问题自测：

15.1 触发维度

• 我能否一眼看出这个 Skill 的适用范围？
• description 是否包含足够的动作词和场景词？
• 它是否容易和别的 Skill 混淆？

15.2 结构维度

• SKILL.md 是否只保留核心流程？
• 详细资料是否下沉到了 references/？
• 需要稳定执行的步骤是否进入 scripts/？

15.3 执行维度

• 如果给出真实任务，代理是否知道先做什么？
• 是否明确写了校验点？
• 出错时能否定位是触发问题、流程问题，还是资源问题？

15.4 维护维度

• 新需求进入时，是扩充参考资料，还是会把 SKILL.md 撑爆？
• 这个 Skill 是否能被他人接手维护？

16. 一套通用的理论框架

你可以用下面这套框架来理解和设计 Skill：

16.1 目标层

回答：这个 Skill 到底解决什么问题。

16.2 触发层

回答：什么请求会触发它。

16.3 流程层

回答：被触发后应该怎么做。

16.4 资源层

回答：需要读哪些参考资料、运行哪些脚本、使用哪些模板。

16.5 校验层

回答：怎么判断做得对不对。

如果一个 Skill 这五层都清楚，通常就不会差。

17. 你在 MediaCrawler 这类项目里可以怎么理解 Skill

对于 MediaCrawler 这种带有采集、处理、格式整理、平台适配特征的项目来说，Skill 特别适合沉淀下面这些能力：

• 某平台的采集规则
• 某类页面的字段提取策略
• 抓取结果的后处理规范
• 自动化测试录制流程
• 特定输出格式的清洗与修复
• 某类异常的排查手册

换句话说，Skill 很适合把“你已经摸索成熟、而且以后还会重复遇到”的东西固化下来。

18. 理论部分的结论

Skill 不是更长的提示词，也不是简单的文档堆积。
它是一种围绕“任务复用、上下文节省、流程稳定、知识按需加载”而设计的工作模块。

真正好的 Skill，核心不是写得多，而是设计得准：

• 触发准
• 范围准
• 流程准
• 资源拆分准
• 验证准

如果你已经理解了这些原理，下一步就不再是“继续看概念”，而是开始实际写一个 Skill。
这部分请看同目录下的 skills_practice.md。