Skill（技能） 是现代 AI Agent（如 Claude、Codex 等）增强能力的主流方式：把某一类任务的「操作手册 + 工具 + 参考资料」打包成一个独立单元，Agent 在需要时自动加载、按章执行。它解决了「靠 prompt 硬塞所有规则」带来的臃肿、不可复用、上下文爆炸问题。
本文从一个真实的 Skill（技术写作技能）切入，讲透 Skill 是什么、三层加载机制怎么工作、SKILL.md 怎么写，以及设计一个好 Skill 的核心原则。如果你正在用 Claude Code / Codex / Cursor 等 Agent 工具，这篇能帮你从「只会写 prompt」升级到「会造工具」。
本文脉络： 一 为什么 prompt 不够用：Agent 增强方式的演进 二 Skill 是什么：三层加载机制 三 SKILL.md 的结构：frontmatter + 正文 四 渐进式披露：Skill 设计的第一原则 五 实战案例：真实技能拆解 + 完整示例 + 怎么使用 六 怎么写好一个 Skill：六个关键原则 七 Skill vs Prompt vs 工具调用：什么时候用哪个 八 常见误区与陷阱 九 速查表
一、为什么 prompt 不够用：Agent 增强方式的演进 先用一个真实的痛点开场。
假设你让 Agent 帮你写技术博客。最朴素的写法是把所有要求塞进 prompt：
你是技术博客写作助手。请遵守： 1. 用中文编号章节（一、二、三） 2. front matter 要有 title/date/categories/tags 3. 开头用引用块，加「本文脉络」目录 4. 要有 ASCII 图、对比表格、代码示例 5. 结尾要有「常见问题」表 6. 代码注释用中文 7. 不要有 AI 味（避免「首先其次最后」「综上所述」） 8. 段落控制在 3-5 行 9. ……还有 20 条规则
这种写法有三个致命问题：
① 臃肿：规则越多，prompt 越长，每次对话都要带上，浪费 token ② 不可复用：换一个项目、换一个 Agent，这套规则得重新抄一遍 ③ 上下文爆炸：prompt 里塞太多规则，会挤占「真正任务」的上下文， Agent 记不住、还会互相冲突 ④ 难维护：规则一多就乱，改一条怕影响别的，没有结构
Agent 增强方式其实经历了几个阶段的演进：
阶段一：单次 prompt 把要求写在对话里 → 用完即弃，下次重来 阶段二：系统 prompt / 角色设定 把通用规则放到 system prompt → 全局生效，但仍然全量加载 阶段三：自定义指令（Custom Instructions） 用户级/项目级的固定指令 → 比 system prompt 灵活，但仍是大段文本 阶段四：Skill（技能） ← 当前主流 把一类任务打包成独立单元，按需加载 → 模块化、可复用、渐进式披露
Skill 的核心突破 在于：它不再是「一大段永远在场的规则」，而是「一份按需加载的操作手册 」——Agent 平时只看到它的名字和简介（几十个字），真正要用时才把完整内容读进上下文。
二、Skill 是什么：三层加载机制 Skill 不是一个 prompt 片段，它是一个目录 ，里面装着 SKILL.md（主文件）和可选的参考资料、脚本、模板。Agent 通过「三层加载」来用它：
┌──────────────────────────────────────────────────────────┐ │ 第 1 层：元数据（Metadata）—— 永远在场 │ │ │ │ 只有 name + description，几十个字 │ │ Agent 每次对话都能看到所有 Skill 的元数据 │ │ 作用：判断「这个任务要不要触发某个 Skill」 │ │ │ │ 例：name: tech-writer │ │ description: 用于撰写技术博客和公众号文章... │ ├──────────────────────────────────────────────────────────┤ │ 第 2 层：SKILL.md 正文 —— 触发后才加载 │ │ │ │ Skill 被触发后，Agent 才把 SKILL.md 完整读进上下文 │ │ 包含：工作流程、规则、示例、产出要求 │ │ 作用：告诉 Agent「这个任务具体怎么做」 │ │ │ │ 目标：控制在 500 行以内 │ ├──────────────────────────────────────────────────────────┤ │ 第 3 层：捆绑文件 —— 按需读取 │ │ │ │ references/（参考资料）、scripts/（脚本）、assets/（模板）│ │ Agent 只在 SKILL.md 指示「需要时」才去读 │ │ 作用：承载大段细节，避免 SKILL.md 膨胀 │ │ │ │ 原则上无大小限制 │ └──────────────────────────────────────────────────────────┘
为什么要分三层 ：如果把所有内容都堆在第 1 层（永远在场），上下文会爆；如果都塞在第 2 层，SKILL.md 会臃肿到 Agent 抓不住重点。分层的好处是——平时极轻，用到才重 。
类比：Skill 就像一本操作手册放在工具箱里 第 1 层：手册封面上的书名和一句简介（你扫一眼就知道有没有用） 第 2 层：翻开手册的正文（你需要时才读） 第 3 层：附录、参考资料、配套工具（用到具体步骤时才翻）
三、SKILL.md 的结构：frontmatter + 正文 每个 Skill 是一个目录，里面必须有 SKILL.md：
my-skill/ ├── SKILL.md ← 必须，主文件 └── (可选) ├── references/ ← 参考资料（Agent 按需读） ├── scripts/ ← 辅助脚本（Agent 可调用） └── assets/ ← 模板、样例
Frontmatter（元数据） --- name: my-skill description: <触发条件 + 做什么> ---
description 是整个 Skill 最重要的字段 ——它决定了 Agent 什么时候会触发这个 Skill。
❌ 写得太弱（Agent 不会触发）： description: 如何写技术文章 ✅ 写得有触发力（明确场景 + 略带主动）： description: 用于撰写和改写技术写作——既覆盖微信公众号文章， 也覆盖 Hexo 博客文章。当用户提到「公众号文章」「博客文章」 「写篇技术文」「把这个改写成公众号/博客风格」、或任何把技术主题 写成面向开发者读者的文章时，使用本技能。
description 的写法要点 ：
写清楚「做什么 」和「什么时候用 」
列举会触发它的用户措辞 （”公众号文章””写篇技术文”）
略带主动——模型倾向于少触发 Skill，描述要稍微”推”它一把
正文（Markdown） 正文用自然语言写工作流程、规则、示例。结构上一般包含：
- 这个 Skill 是干什么的（一句话定位） - 触发后该怎么做（分步骤的工作流程） - 关键规则（用什么形式输出、避免什么） - 示例（比规则更管用） - 产出物清单（交付什么）
关键认知 ：正文是写给 Agent 读的，但用的是自然语言 ——不是代码，不是 YAML，就是结构化的 Markdown。Agent 能理解自然语言指令，所以你写得像「给同事的操作指南」就行。
四、渐进式披露：Skill 设计的第一原则 这是设计 Skill 最重要的一条原则：不要把所有细节都塞进 SKILL.md 。
反例（一次性全塞）： SKILL.md 里写了 2000 行，涵盖 AWS/GCP/Azure/阿里云 四种部署的完整细节 → Agent 每次触发都要读 2000 行，其中 3/4 和当前任务无关，浪费上下文 正例（渐进式披露）： SKILL.md 只写通用的工作流程和「选型决策」（200 行） references/ 下分 aws.md / gcp.md / azure.md / aliyun.md SKILL.md 里写： "如果目标是 AWS，在读后续步骤前，先读 references/aws.md" → Agent 触发时只读 200 行，确认是 AWS 后才读 aws.md，上下文干净
渐进式披露的三层结构： cloud-deploy/ ├── SKILL.md ← 工作流程 + 选型（轻量，~200 行） └── references/ ├── aws.md ← AWS 专属细节（按需读） ├── gcp.md ├── azure.md └── aliyun.md
为什么有效 ：
① 平时省上下文：不触发的 Skill 只占元数据那几十个字 ② 触发后省上下文：SKILL.md 只放「共性」，细节按需加载 ③ 可扩展：加一种云，只需加一个 reference 文件，不动 SKILL.md
判断该放哪一层的口诀 ：
所有任务都用得到 → SKILL.md 正文
只有特定子场景用得到 → references/ 下单独成文
五、实战案例：真实技能拆解 + 完整示例 + 怎么使用 讲了这么多原则，来看一个真实的 Skill。这是一个用于「技术写作」的技能，覆盖博客文和公众号文两种模式。
目录结构 tech-writer/ └── SKILL.md ← 单文件，暂未拆 references
Frontmatter --- name: tech-writer description: 用于撰写和改写技术写作——既覆盖微信公众号/知乎/掘金等 自媒体文章，也覆盖本项目（tiny-blog，Hexo）的技术博客文章。 当用户提到「公众号文章」「博客文章」「写篇技术文」「把这个改写成 公众号/博客风格」、或任何把技术主题写成面向开发者读者的文章时， 使用本技能。本技能会根据目标载体在「公众号模式」和「博客模式」 间切换。 ---
注意 description 里干了两件事：① 列举触发措辞（公众号/博客/技术文/改写）② 明确告知有「双模式」切换。这让 Agent 既知道何时触发，又对触发后要做什么有预期。
正文的核心设计 这个 Skill 正文最有特色的地方是**「双模式」作为骨架**：
# 技术写作 把技术内容写成适合阅读和传播的文章。本技能覆盖两种载体， 写作前必须先判断走哪种模式： | 模式 | 载体 | 读者状态 | 核心目标 | |------|------|---------|---------| | 公众号模式 | 微信公众号、知乎、掘金 | 被动刷信息流、随时划走 | 抓住注意力，让人读完 | | 博客模式 | Hexo 博客（source/_posts/）| 主动检索、带着目的来读 | 讲完整、讲准确 | 第一步：判断走哪种模式（动笔前必做） 如果用户已明说（「写篇公众号文」「加篇博客」），按说的来。 否则根据线索判断，拿不准就直接问一句： 「公众号」「传播」「转发」→ 公众号模式 「博客」「写进 _posts」「长期沉淀」→ 博客模式
这个设计体现了 Skill 的一个强大之处：它能让 Agent 在不同场景下按不同规则工作，而不用写两个 Skill 。模式判断逻辑写在正文里，Agent 读到后自然会先判断再执行。
「去 AI 味」作为共通心法 这个 Skill 还内嵌了一个跨模式的通用原则——「去 AI 味」。它没有抽象地说「请写得自然」，而是给了对照示例 ：
❌ AI 味：「限流不仅保护了下游，更提升了系统稳定性，还守护了用户体验。」 ✅ 人味：「说白了，限流就是用『拒绝一部分请求』换『核心服务别挂』。」
❌ AI 味：「在微服务架构日益普及的今天，稳定性成为了重要课题。」 ✅ 人味：「上周我们一个下游服务挂了 3 分钟，上游线程池被打满，差点雪崩。」
为什么对照示例比规则管用 ：模型从具体例子中学到的风格，远比从「请写得自然些」这种抽象指令中学到的多。这是 Skill 编写的一个核心技巧——examples beat rules（示例胜过规则） 。
5.4 一个完整的 Skill 示例 上面是片段，这里给一个完整、自包含、可直接复制使用 的 SKILL.md——就是贯穿本文的 tech-writer 的精简版。它把双模式、去 AI 味、对照示例都浓缩在一个文件里。
目录结构 ：
tech-writer/ └── SKILL.md ← 单文件（规则不多时无需拆 references）
SKILL.md 完整内容 ：
--- name: tech-writer description: 用于撰写和改写技术写作——既覆盖微信公众号等自媒体文章， 也覆盖技术博客文章。当用户提到「公众号文章」「博客文章」「写篇技术文」 「把这个改写成公众号/博客风格」、或任何把技术主题写成面向开发者读者的 文章时使用。本技能会根据目标载体在「公众号模式」和「博客模式」间切换。 --- # 技术写作 把技术内容写成适合阅读和传播的文章。本技能覆盖两种载体，写作前必须先判断 走哪种模式： | 模式 | 载体 | 读者状态 | 核心目标 | |------|------|---------|---------| | 公众号模式 | 微信公众号、知乎、掘金 | 被动刷信息流、随时划走 | 抓住注意力，让人读完 | | 博客模式 | 技术博客（source/_posts/）| 主动检索、带着目的来读 | 讲完整、讲准确 | ## 第一步：判断走哪种模式（动笔前必做） 用户已明说（「写篇公众号文」「加篇博客」）按说的来。否则根据线索判断， 拿不准就直接问一句： 「公众号」「传播」「转发」→ 公众号模式 「博客」「写进 _ posts」「长期沉淀」→ 博客模式## 共通心法：去 AI 味（每篇必查） AI 味的本质是「像在交作业，不像在跟人说话」。六大典型症状及改法： 排比收尾： ❌ 「限流不仅保护了下游，更提升了稳定性，还守护了体验。」 ✅ 「说白了，限流就是用『拒绝一部分请求』换『核心服务别挂』。」 空话开场： ❌ 「在微服务架构日益普及的今天，稳定性成为了重要课题。」 ✅ 「上周我们一个下游服务挂了 3 分钟，上游线程池被打满，差点雪崩。」 去味心法：写之前先想「这话我会在群里跟同事怎么说」，用口语节奏写， 再书面化润色。 ## 公众号模式 读者在手机刷信息流，节奏必须快： - 标题先行：先定 2-3 个候选标题，和用户对齐再写正文- 开头钩子：用真实场景/痛点/事故切入，不要「今天我们聊聊 XX」- 段落控制在 3-5 行（手机一屏），关键结论单独成行加粗- 代码块不超过 15 行，长代码裁剪成关键片段## 博客模式 读者主动来查资料，严谨、完整、可检索比花哨重要： - front matter：title / date / categories / tags 齐全- 引用块开头 + 「本文脉络」目录 + 编号章节- 多用 ASCII 图、对比表格、代码示例- 结尾给「常见问题 / 速查表」这类收藏点## 产出物 1. 2-3 个候选标题（标注推荐项）2. 完整正文（markdown，已按对应模式排版）
这个示例体现了什么 ：
frontmatter 的 description 列举了触发措辞（「公众号文章」「博客文章」），并预告「双模式」
正文用**「双模式」作为骨架**，Agent 读到后会自动先判断模式再执行
「去 AI 味」用对照示例 呈现（❌ vs ✅），而不是抽象规则——examples beat rules
共通常识放前面，两种模式各自的规则分块——结构清晰，Agent 能按场景取用
5.5 Skill 怎么使用 写好 Skill 只是第一步，还得知道怎么让它被 Agent 用上 。流程分三步：放置 → 触发 → 执行。
第一步：放到正确的目录
不同 Agent 工具的 Skill 发现路径不同，以 Codex / Claude Code 类工具为例，Skill 按作用域放在约定目录下：
作用域优先级（从高到低）： <项目>/.codex/skills/<name>/SKILL.md ← 项目级，仅当前仓库生效 <项目>/.agents/skills/<name>/SKILL.md ← 项目级（跨工具通用位置） ~/.codex/skills/<name>/SKILL.md ← 用户级，所有项目生效 ~/.agents/skills/<name>/SKILL.md ← 用户级（跨工具通用位置）
选哪个？ - 只在某个项目里用（如本项目专用的 tech-writer） → 项目级 - 所有项目都想用（如通用的代码审查技能） → 用户级
第二步：触发 Skill
Skill 有两种触发方式：
① 自动触发（主要方式） Agent 每次对话都能看到所有 Skill 的元数据（name + description）。 当用户的请求匹配某个 Skill 的 description 时，Agent 自动加载它。 例：用户说「帮我写篇公众号文章」 → Agent 看到 tech-writer 的 description 里有「公众号文章」 → 自动触发，加载 SKILL.md 正文 ② 强制触发（调试/兜底） 用斜杠命令直接指定，不依赖 description 匹配： /skill tech-writer 把熔断文改成公众号风格 适用：description 写得不够、Agent 没自动触发时，手动调起
第三步：Agent 执行流程
Skill 触发后，Agent 内部的完整执行链路：
用户：「把熔断文改写成公众号风格」 ↓ Agent 扫描所有 Skill 的 description ↓ 命中 tech-writer 加载 SKILL.md 正文（第 2 层） ↓ 读到「第一步：判断走哪种模式」 判断：用户说「公众号风格」→ 公众号模式 ↓ 按「公众号模式」的规则写作 调用工具：读取熔断文（Read）→ 写入新文件（Write） ← 工具调用 ↓ 写完初稿，套用「去 AI 味」清单自查 按需对照「去 AI 味」的对照示例修正表达 ← 共通心法（按需） ↓ 输出：公众号风格的文章（交付给用户）
注意这条链路里三层加载 + 工具调用是协同的 ：
第 1 层（description）让它知道「该触发」
第 2 层（SKILL.md）告诉它「怎么做」（先判模式，再按规则写）
共通心法（去 AI 味）在「需要修正表达」时才套用
工具调用（Read/Write）让它能「真正读写文件」
验证 Skill 是否生效 ：
写完 Skill 后，用这三个 prompt 测一遍： 1. 自动触发测试：说一句能匹配 description 的话，看 Agent 有没有自动用上 （比如直接说「帮我写篇技术文」，而不是「用 tech-writer 技能」） 2. 强制触发测试：用 /skill tech-writer 显式调起，确认 Skill 内容能正确加载 3. 边界测试：故意说一句模糊的话（如「整理一下这篇文章的排版」）， 看 Agent 能否合理判断要不要触发——避免过度触发或漏触发
六、怎么写好一个 Skill：六个关键原则 1. description 要有触发力 模型倾向于少触发 Skill，所以 description 要写清楚场景、列举用户措辞，甚至可以略带「推销」语气。
弱：description: 如何构建仪表盘 强：description: 如何为内部数据构建快速仪表盘。当用户提到仪表盘、 数据可视化、内部指标，或想展示任何公司数据时使用—— 即使用户没明说「仪表盘」也要触发。
2. 正文控制在 500 行以内 SKILL.md 太长会导致 Agent 抓不住重点、还会挤占上下文。超过 500 行就该考虑拆分到 references/。
3. 用示例代替规则 模型跟着例子学，比跟着规则学更准。如果 Skill 产出结构化内容，给一个字面示例 ；如果要用某个工具，给一个调用示例 。
4. 解释「为什么」，而不只是下命令 弱：必须先 Read 文件再 Edit。 强：先 Read 文件再 Edit——因为 Edit 工具要求 old_string 精确匹配， 不先读就拿不到准确内容，Edit 会失败。
模型理解了原因，在边界情况下能自己做出正确判断，而不是机械执行。
5. 渐进式披露，别一次塞满 共性放 SKILL.md，特定子场景的细节放 references/，按需加载（见第四章）。
6. 写完要测，别交付即结束 Skill 写完后，拿 2-3 个真实 prompt 测一遍：① 看描述能不能触发它 ② 看产出符不符合预期 ③ 看有没有让 Agent 绕弯路。根据测试结果迭代，而不是写完就用。
七、Skill vs Prompt vs 工具调用：什么时候用哪个 这三个概念容易混，其实分工不同：
维度
Prompt（指令）
工具调用（Tool/Function）
Skill（技能）
本质
一次性的任务描述
Agent 调用外部能力的接口
打包的「操作手册 + 工具 + 资料」
复用性
用完即弃
可复用，但只是「能力点」
高度复用，是「能力包」
加载方式
每次手动给
注册后可调用
按需自动加载
适合
一次性、临时的任务
需要「执行动作」（查 DB、调 API）
一类反复出现的任务
例子
“帮我把这段代码格式化”
查数据库、发请求、读写文件
技术写作、代码审查、部署流程
三者的关系（不是互斥，是协同）： Skill 里可以包含「该用哪个工具」「怎么用工具」的指导 Prompt 可以触发 Skill，Skill 执行中又会调用工具 例：tech-writer（Skill）被「写篇博客」(Prompt) 触发， 执行中可能调用 Read/Write（工具）来读写文件
选型口诀 ：
一次性、简单 → Prompt
需要执行外部动作 → 工具调用
一类反复出现的复杂任务 → Skill
八、常见误区与陷阱
误区
后果
对策
description 写得太弱 Agent 不触发，Skill 形同虚设
列举触发措辞，略带主动
SKILL.md 太长 Agent 抓不住重点，上下文被挤占
控制在 500 行，细节拆到 references/
全是规则没有示例 Agent 理解偏差，产出不稳定
关键产出给字面示例
只下命令不讲原因 边界情况下 Agent 机械执行出错
解释 why，让 Agent 能自己判断
写完不测就用 触发不稳定、产出跑偏
拿 2-3 个真实 prompt 测，迭代
一个 Skill 想干所有事 职责混乱，触发条件冲突
一个 Skill 聚焦一类任务
目录名和 name 不一致 Agent 加载异常
name 必须 = 目录名（kebab-case）
九、速查表
你可能想问
一句话答案
Skill 是什么？
打包了「操作手册 + 工具 + 参考资料」的独立单元，Agent 按需加载
和 prompt 的区别？
Prompt 是一次性指令，Skill 是可复用、模块化、按需加载的能力包
怎么决定何时触发？
看 description——它是最关键的触发信号，要写清场景和用户措辞
三层加载是什么？
元数据（永远在场）→ SKILL.md（触发后加载）→ references（按需读）
最关键的设计原则？
渐进式披露：共性放正文，细节按需加载，别一次塞满
SKILL.md 多长合适？
控制在 500 行以内，超了就拆 references/
怎么让产出稳定？
给对照示例（examples beat rules），不只写规则
什么时候该用 Skill？
一类反复出现的复杂任务（如技术写作、代码审查、部署流程）
有完整示例可参考吗？
见 5.4 的「tech-writer」精简版——双模式骨架 + 去 AI 味对照示例
Skill 写好怎么用？
放到约定目录 → 自动触发（靠 description）或强制触发（/skill）→ Agent 三层加载执行
放项目级还是用户级？
只在某个仓库用 → 项目级；所有项目都用 → 用户级
一句话总结 ：Skill 的本质，是把「反复出现的任务经验 」从 prompt 里抽出来，打包成 Agent 能按需加载的工具——平时极轻，用到才重。写好它的关键不是堆规则，而是：清晰的触发条件 + 渐进式披露的结构 + 能让模型学会的示例 。