一、写在前面

Skill 的本质不是知识库，而是行为编程，目标不是让人读懂，而是让 Agent 在压力下也走不偏。

你有没有遇到过这种情况：给 Agent 配了一份写得清清楚楚的 Skill 说明，结果它一进入复杂任务，该抄的近道还是抄了，该踩的坑一个没躲过。你可能会觉得是"没写清楚"，但更大概率，是从一开始就把 Skill 当成了文档来写。

这篇文章想聊透一个核心判断：Skill 不是知识库，是行为编程。它的目标从来不是"让人类看懂"，而是让 Agent 在上下文不够、任务复杂、目标冲突、执行有压力这些最容易"翻车"的场景里，依然按你设计好的路径走下去。

一个真正合格的 Skill，要同时做对四件事：

• 让 Agent 在正确场景发现它
• 用最少的上下文加载必要信息
• 按任务风险给出合适的自由度
• 用真实任务验证它是否真的改变了行为

接下来，本文会把这四件事拆成九个可落地的模块，从命名规范、目录结构一路讲到自由度设计、验证方法论，再到跨平台适配和交付自查，目标是帮你写出能被 Agent"正确触发、正确执行、持续维护"的 Skill。

二、Skill 的本质：能力包，不是知识库

先说清楚一个常被搞反的定位：Skill 更接近"能力包"，而不是"知识库"。它由 SKILL.md、脚本、引用资料、资产这几类材料组合而成，作用是把一个什么都懂一点的通用 Agent，打磨成在某个具体任务上靠谱得多的专用 Agent。拆开看，一个完整的 Skill 通常提供四类能力：

能力	说明	示例
专用工作流	多步骤、可复用的任务流程	写技术方案、处理 PR 评论、生成报告
工具集成	使用特定文件格式、API 或 CLI 的方法	处理 PDF、调用 GitHub、操作表格
领域知识	业务规则、数据口径、组织约定	公司指标口径、内部权限边界
捆绑资源	脚本、模板、参考资料、素材	scripts/、references/、assets/

这里有个容易被忽略、却特别关键的设计前提：Skill 面对的是 Agent，而 Agent 在上下文不够、任务复杂、目标有冲突、执行有压力的时候，本能反应就是找近道走。所以写 Skill 不能假设对方会乖乖照办，反而要反过来预设"它一定会想抄近道"，再把正确路径设计得比近道更顺手。

基于这个前提，Skill 不该是人类背景知识的搬运工，它该补的，是 Agent 完成任务时真正缺的东西：程序性知识、资源边界、验证方式。说直白点，写 Skill 不是"把话讲清楚"，而是"让 Agent 在复杂环境里更难走偏"。

要让 Skill 真正起作用，它得覆盖 Agent 完整的行为链路，也就是提前想清楚这七件事：

• 什么时候会被发现
• 什么时候该加载完整正文
• 哪些信息只需要按需查阅
• 哪些动作是前置的、必须先做
• 哪些行为是绝对的红线
• 怎么算是真的完成了任务
• 什么时候该停下来，把判断权交回给人

 一个简单的判断标准：如果一个 Skill 只有在"模型状态好、上下文够用、任务简单"的理想情况下才管用，它其实还是个提示词模板。真正合格的 Skill，得扛得住任务复杂、信息缺失、执行有压力、Agent 想走捷径这些真实世界的考验。

三、上下文是公共资源：元数据、正文、资源三层加载

Skill 设计的第一条工程原则，也是最容易被忽视的一条：上下文窗口是公共资源。

Agent 干活的时候，上下文窗口要同时塞下系统提示词、用户请求、历史对话、已触发的 Skill、工具返回结果、代码片段和中间推理。Skill 每多占一个 token，留给其他内容的空间就少一个。所以写 Skill 的默认前提应该是：Agent 已经足够聪明，你只需要补它不知道、但完成任务必须知道的部分。

每写一段文字，不妨拿两个问题过一遍：

• Agent 真的需要这段解释吗？
• 这段内容配得上它占用的 token 成本吗？

这也是为什么 Skill 要做渐进披露，而不是把所有信息一股脑塞进一个长文件。一个标准的 Skill 目录，通常是这样：

skill-name/
  SKILL.md
  agents/
    openai.yaml
  scripts/
  references/
  assets/

其中只有 SKILL.md 是必需的，其余资源都按需添加。三层加载各自的职责分工如下：

层级	载入时机	作用	写作原则
元数据层	通常始终可见	让 Agent 判断是否触发	短、准、覆盖触发场景
正文层	Skill 触发后	提供核心流程和边界	只保留执行必需内容
资源层	任务需要时	承载细节、脚本、模板	按需读取或执行

SKILL.md 的 frontmatter 和正文，也要各自负责不同的事：

---
name: create-skill
description: 用于创建或更新包含工作流、工具集成、领域知识、脚本、参考资料或资产的 Agent Skill。
---
# 创建 Skill
流程：
1. 理解具体示例。
2. 规划可复用资源。
3. 初始化 Skill。
4. 编辑 SKILL.md 和相关资源。
5. 验证。
6. 结合真实使用持续迭代。

name 和 description 属于发现层，正文属于执行层，这两层千万别混着写。

description 得同时讲清楚"这个 Skill 做什么"和"什么时候用它"，因为 Agent 只有在被触发之后才会去读正文；要是把触发条件塞进正文里的"何时使用"，Agent 在判断该不该触发的那一刻，根本看不见这段话。但 description 也不能反过来变成完整工作流的摘要，它唯一该干的事，是让 Agent 准确加载正文，而不是让 Agent 读完描述就凭印象直接上手。

命名同样是发现机制的一环。一个好的 Skill 名字应该短、能触发联想、动词打头：

好名字	问题名字	原因
create-skill	skill-creation-methodology	动词入口更像可执行动作
gh-address-comments	github-pr-review-feedback-helper	命名空间明确，长度更可控
linear-address-issue	issue-processing	触发对象更清楚

这些细节看着像命名规范，本质上是路由质量的问题。Agent 是在一个不断变大的技能库里找能力，name 和 description，就是它能看到的第一层索引。

四、把可复用部分外置：脚本、引用、资产各司其职

创建 Skill 时，不建议一上来就闷头写长篇 SKILL.md。更稳妥的路径是先攒几个具体案例，再判断哪些内容真正值得沉淀成可复用资源。

资源	适合放什么	不适合放什么
scripts/	反复执行、容易写错、需要确定性的操作	只用于解释概念的示意代码
references/	schema、API 文档、政策、长示例、领域规则	每次执行都必须读的核心流程
assets/	模板、图片、字体、样例工程、PPT 母版	需要被读入上下文的大段说明

同一段代码会被反复重写，或者任务需要确定性时，放进 scripts/：

pdf-editor/
  SKILL.md
  scripts/
    rotate_pdf.py

脚本的价值不是"让目录看起来更丰富"，而是压缩上下文消耗、遏制行为漂移。让 Agent 每次都临时手写一遍 PDF 旋转代码，和让它直接调用一个已经跑通验证过的脚本，是两个完全不同量级的可靠性。

信息是任务执行时需要查阅的知识，而不是每次都必须读的流程时，放进 references/：

big-query/
  SKILL.md
  references/
    schema.md
    finance.md
    product.md

比如：用户问的是销售指标，Agent 理应只读 sales.md 或对应领域的文件，没必要把财务、产品、市场的规则一次性全部加载进来。这正是渐进披露在真实 Skill 里的价值所在：信息可以被找到，但不会抢占上下文。

文件不会被读入上下文、而是作为产出物被复制或引用时，放进 assets/：

frontend-webapp-builder/
  SKILL.md
  assets/
    hello-world/

模板工程、字体、图片、PPT 模板、品牌素材，都归在这一类。它们不是给 Agent"阅读"的长文本，而是给最终产物"直接使用"的材料。

一条经常被忽视的原则：同一条信息只该存在于一个地方。别在 SKILL.md 和 references/ 里重复写同一段规则，重复会带来漂移，漂移会逼着 Agent 在两个版本之间自己"猜"该信哪个，最后维护成本会直接转化成执行风险。

五、用任务风险决定自由度：文本、模板、脚本、门控

Skill 不是写得越细越好，也不是给的自由度越大越好。真正的关键在于：让自由度匹配任务本身的脆弱程度和变化空间。

Skill 的控制方式大致可以分成三档：

自由度	适用场景	表达方式
高自由度	多种做法都合理，需要结合上下文判断	文本原则、启发式规则
中自由度	有推荐模式，但允许参数变化	伪代码、参数化脚本、模板
低自由度	操作脆弱、容易出错、必须一致	固定脚本、少量参数、明确顺序

举几个例子会更直观：

• 写技术文章：适合高自由度，靠结构原则、语气规则和示例来引导
• 查询内部指标：适合中自由度，用 SQL 模板加字段说明来控制口径
• 旋转 PDF、转换格式、生成固定报告：适合低自由度，直接靠脚本保证确定性

这里有两种方向相反、但同样常见的错误。一种是把脆弱操作写成"开放式建议"，结果 Agent 每次都得重新推导一遍容易出错的逻辑；另一种是把本该靠判断力的任务写成死板流程，导致 Skill 到了真实场景里完全没弹性、也没法迁移。

在低自由度任务里，门控（gate）格外重要。如果 Skill 只写"建议先做 A"，Agent 很可能直接一步跳到 B。门控的作用，是在条件没满足之前，硬性禁止后续动作：

<HARD-GATE>
在理解具体使用示例并规划好可复用资源之前，不要创建或编辑该 Skill。
</HARD-GATE>

常见的门控类型有这几种：

门控类型	用途	示例
前置门控	完成 A 才能开始 B	先理解例子，再设计资源
上下文门控	特定角色或环境跳过流程	子智能体不加载入口 Skill
验证门控	有证据才能声明完成	quick_validate.py 通过后再交付
审查门控	审查通过才能继续	计划通过后再实现

门控不是措辞上的问题，而是执行边界。它压缩的是 Agent 的"自我解释空间"，让 Skill 在关键路径上更像一段程序，而不只是一句友情提示。

六、从例子到 Skill：把流程写成可执行路径

一套相对稳妥的 Skill 创建流程，可以拆成六步：

• 理解具体使用例子
• 规划可复用资源
• 初始化 Skill
• 编辑 SKILL.md 和资源
• 验证 Skill
• 基于真实使用持续迭代

这条流程真正的重点，不是"先写一份漂亮的说明"，而是先把使用边界划清楚。

所以别从抽象能力直接下笔，先问自己几个问题：

• 用户会怎么触发它？
• 哪些请求该触发，哪些不该？
• 任务输入是什么？
• 成功的输出长什么样？
• 哪一步最容易出错？

比如要做一个 pdf-editor Skill，应该先收集"旋转 PDF"、"合并 PDF"、"提取页面"这类具体请求，再决定要不要写脚本。没有具体例子打底，很容易写出一个看着面面俱到、实际根本没法执行的 Skill。

把每个例子从零跑一遍，就能识别出哪些部分真正值得沉淀：

发现	资源选择
同一段代码反复出现	放进 scripts/
每次都要查 schema 或规则	放进 references/
每次都要复制模板或素材	放进 assets/
只是几条核心判断原则	留在 SKILL.md

当 Skill 里有非线性判断、循环、回退，或是容易被提前中断的步骤时，流程图会比纯文字稳得多。GraphViz DOT 是一种很适合嵌进 Markdown 的轻量格式：

digraph {
  "是否有具体使用例子?" [shape=diamond];
  "收集或生成例子" [shape=box];
  "规划 scripts/references/assets" [shape=box];
  "编写 SKILL.md" [shape=box];
  "运行 quick_validate.py" [shape=box];
  "完成" [shape=doublecircle];


  "是否有具体使用例子?" -> "规划 scripts/references/assets" [label="yes"];
  "是否有具体使用例子?" -> "收集或生成例子" [label="no"];
  "收集或生成例子" -> "规划 scripts/references/assets";
  "规划 scripts/references/assets" -> "编写 SKILL.md";
  "编写 SKILL.md" -> "运行 quick_validate.py";
  "运行 quick_validate.py" -> "完成";
}

复杂流程还应该配一份编号检查表，并要求 Agent 把进度显式记录下来，不然 Agent 很容易走完前几步，就把后面的验证和迭代忘得一干二净。

初始化 Skill 时，建议直接用初始化脚本，而不是手动搭目录：

scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"

如果需要资源目录：

scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources scripts,references

初始化脚本的意义在于减少结构性失误、直接生成符合规范的模板，剩下的工作只是替换占位内容、删掉不需要的示例文件。

七、验证不是收尾动作：保护测试完整性，防止合理化

Skill 不该写完就冻结。它的质量应该来自真实的行为反馈，而不是作者对流程的自我想象。

写完之后第一步，先跑基础验证：

scripts/quick_validate.py <path/to/skill-folder>

基础验证至少要覆盖：

• YAML frontmatter 是否合法
• name 和 description 是否存在
• 命名是否符合规则
• 资源目录是否合理
• 脚本是否能跑通
• UI 元数据是否与 SKILL.md 同步

格式验证证明不了 Skill 一定好用，但至少能先筛掉一批低级错误。复杂 Skill 还需要前向测试，可以用子智能体去模拟真实用户任务，但要把它当成"评估面"，而不是"审稿人"。

正确的做法是这样：

使用位于 /path/to/skill-x 的 @skill-x 来解决问题 y。

不好的做法是这样：

审查这个 Skill。我认为它存在问题 A，预期的修复方案是 B。

后一种做法会提前把诊断结论和预期答案泄露出去，测试结果自然就被污染了。前向测试应该只给子智能体原始任务、原始材料和最少必要的上下文，让它像一个真实用户那样自己摸索着走一遍。

验证时，应该优先看这些第一手证据：示例 prompt、输出文件、diff、日志、行为轨迹、失败截图、测试结果。如果子智能体只有在看到你的结论之后才能把任务做成，那说明 Skill 本身还不够清楚，或者测试设置已经提前泄了题。

这里还得处理一个 Agent 特有的毛病：合理化。AI Agent 在压力之下，特别擅长给"跳过规则"找一个听起来挺合理的理由。所以 Skill 应该提前把这些借口列出来，并配上反驳：

常见借口	应写进 Skill 的反驳
"这个 Skill 很简单，不需要例子"	没有例子就不知道触发边界，也不知道需要哪些资源
"先写 SKILL.md，之后再补资源"	资源设计决定正文结构，后补容易造成重复和上下文膨胀
"脚本很短，每次生成也可以"	重复生成的脆弱代码会漂移，脚本能提供确定性
"验证只是格式检查，可以跳过"	格式错误会直接影响发现和加载，必须尽早暴露
"子智能体看一下就行"	验证不能泄露预期答案，否则测的是复述能力，不是泛化能力

审查循环也该围绕"真实失败风险"展开，而不是纠结措辞偏好：

写或修改 Skill
-> 运行格式验证
-> 用真实任务前向测试
-> 是否存在会导致任务失败的问题？
-> 是：修复并重测
-> 否：交付

该被拦下的问题包括：触发条件模糊、资源引用缺失、脚本跑不通、验证流程缺失、自由度设置错误、关键信息重复且容易漂移。不该被拦下的问题包括：纯粹的风格偏好、不影响执行的标题顺序、可以交给 Agent 自行判断的轻微表达差异。

八、处理生态边界：发现、依赖、平台适配

技能库一旦变大，发现机制就会变成第一个瓶颈。这里要记住一句话：description 是路由器，不是教程。

它该覆盖：Skill 做什么、什么时候用、典型触发词、相关症状、输入或任务类型。但绝对不该把完整执行流程也塞进去。

对比一下会更直观。

错误写法：

description: "创建 Skill 时先收集例子，再规划 scripts/references/assets，然后运行 init_skill.py，最后 quick_validate.py。"

更好的写法：

description: "用于创建或更新包含专用工作流、工具集成、领域知识、捆绑脚本、参考资料、资产、验证或迭代机制的 Agent Skill。"

前一种写法容易让 Agent 光凭 description 就动手，直接跳过正文；后一种能让 Agent 准确判断该不该触发，但仍然需要加载正文才能拿到完整流程。

Skill 之间也可以互相引用，但要声明清楚彼此的关系，而不是硬编码路径或强行加载大文件：

**必需子 Skill：** 创建新 Skill 前，先使用 skill-x。
**推荐：** 如果要将其发布为开发者文章，使用 skill-y。
**另见：** openai_yaml.md，了解 UI 元数据字段。

引用大致可以分成三层：

级别	语义	使用时机
REQUIRED	必须先加载	前置依赖
RECOMMENDED	建议加载	能明显提高质量
SEE ALSO	可选参考	扩展阅读

千万别用"一次性强制加载大量内容"的方式去拼装 Skill，那样会直接破坏渐进披露，也会让组合出来的 Skill 成本彻底失控。

最后是平台适配的问题。不同平台的工具名、hook、插件机制、子智能体能力可能都不一样。Skill 应该尽量只写行为规则，具体工具的适配交给平台层去做：

- TodoWrite -> todowrite
- Task tool -> @mention subagent system
- Skill tool -> native skill tool

如果平台能力跟不上，应该优雅降级：

缺失能力	降级策略
无子智能体	回退到单会话执行
无启动 hook	用系统提示词或入口 Skill 注入
无后台进程	使用前台执行
无 bash	跳过脚本能力，保留文档和资源指导

这样处理下来，Skill 会更容易迁移，也更省心维护，真正该保持稳定的是行为规则本身，而不是某个平台的私有工具名。

九、交付前自查：反模式和检查表

不少 Skill 之所以失败，并不是作者不懂领域知识，而是他把"人类文档"那一套写法，原封不动地带进了"Agent 执行系统"里。

常见反模式：

反模式	表现	修正
把 Skill 当文档	背景很长，流程很散	只保留可执行知识
description 写成教程	Agent 不读正文就开始执行	描述只负责触发
自由度不匹配	脆弱任务只给建议，开放任务写死流程	按任务风险设置自由度
资源不分层	所有内容塞进 SKILL.md	用 scripts/、references/、assets/ 分离
重复信息	正文和引用文件都有同一规则	信息只放一个地方
跳过验证	写完就交付	运行格式验证和真实任务测试
验证泄露答案	子代理知道预期修复	只给原始任务和材料
额外文档膨胀	创建 README、安装指南、变更日志	只保留执行必需文件

交付前，可以直接拿这张表自查一遍：

检查项	问题
具体例子	是否知道用户会怎样触发它？
触发描述	description 是否覆盖使用场景，但没有泄露完整流程？
命名	是否短、动词优先、符合 kebab-case？
自由度	是否按任务脆弱度选择文本、伪代码或脚本？
资源分层	是否把脚本、引用、资产放在正确位置？
渐进披露	SKILL.md 是否只保留核心流程？
引用清晰	是否明确什么时候读取哪个 reference？
去重	同一信息是否只存在于一个地方？
验证	是否运行了基础验证和必要脚本？
前向测试	复杂 Skill 是否用真实任务测试过？
迭代入口	是否知道真实使用失败后该改哪里？

要是这张表里有好几项都答不上来，说明这个 Skill 还没到"能力包"的程度，充其量算是一份草稿。

十、写在最后：好 Skill，是一个小而准的行为系统

写 Skill，从来不是把一堆最佳实践攒成一篇 Markdown。真正的 Skill 设计，得能回答三个问题：

• Agent 在什么情况下应该发现并加载它？
• Agent 该拿到多少自由度，哪些部分必须被脚本或门控锁死？
• 我们怎么用真实任务证明，它确实改变了 Agent 的行为？

如果一定要用一句话总结全文，大概是：Skill 要简洁、分层、可验证、可迭代。上下文窗口是公共资源，SKILL.md 只留核心流程；脚本负责确定性，引用负责领域知识，资产负责输出材料；复杂 Skill 一定得靠真实任务的前向测试来验证，而不是靠作者自己觉得靠谱。

说到底，Skill 是 Agent 行为设计的一种工程方法论。它把触发、加载、执行、约束、验证、迭代这几件事系统地组织在一起，让一个通用 Agent，能在特定任务上稳定地表现出专业水准。

  学习资源推荐

如果你想更深入地学习大模型，以下是一些非常有价值的学习资源，这些资源将帮助你从不同角度学习大模型，提升你的实践能力。

一、全套AGI大模型学习路线

AI大模型时代的学习之旅：从基础到前沿，掌握人工智能的核心技能！​

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

二、640套AI大模型报告合集

这套包含640份报告的合集，涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师，还是对AI大模型感兴趣的爱好者，这套报告合集都将为您提供宝贵的信息和启示

​因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

三、AI大模型经典PDF籍

随着人工智能技术的飞速发展，AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型，如GPT-3、BERT、XLNet等，以其强大的语言理解和生成能力，正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

四、AI大模型商业化落地方案

作为普通人，入局大模型时代需要持续学习和实践，不断提高自己的技能和认知水平，同时也需要有责任感和伦理意识，为人工智能的健康发展贡献力量。