这篇是我整理的一份 Skills 相关笔记。我想先理清它在 Agent 系统中的位置,再看看一份 Skill 怎样从文件夹里的文字,变成任务执行时用到的指导。
文章会先用图把组成关系和加载过程展开,再结合 Codex 的 Skill Creator 梳理编写方法。如果你也想把日常使用 Agent 的一些做法整理下来,欢迎一起读下去,也欢迎分享你的理解。
1 概念定位:Skill 在 Agent 系统中负责什么
使用动机:为什么我们需要 Skill
模型已经能理解代码、组织文字,也能在工具帮助下处理文件。但真正做一项具体工作时,仍有许多信息需要由使用者提供:项目采用什么约定,哪些资料可信,结果交付到哪里,遇到不同情况应怎样处理,以及什么程度才算完成。
这些信息里,有些只属于眼前的任务,例如这次要改哪篇文章;有些会反复出现,例如技术结论要查原始资料、框架确认后才写正文、配图优先复用合适的原图。后一类方法如果每次都重新交代,既费力,也容易在新对话中漏掉。
Skill 把这类任务知识组织成可复用的文件包。它以 SKILL.md 为入口,保存指令,并按需要附带参考资料、脚本和素材。运行 Agent 的应用或框架通常称为宿主。支持 Skill 的宿主负责发现和加载这些文件,模型再结合当前任务使用其中的指导。这也是 Agent Skills 开放规范对它的基本定位。
它保存的内容可以是一套工作流程,也可以是某个领域的判断标准、数据含义或工具用法。知识通过上下文参与推理;对于适合程序处理的部分,还可以调用包内脚本。模型参数没有因此改变,效果仍取决于指导是否准确、当前任务是否适合,以及执行环境是否具备所需能力。
我更关注的是:把哪些方法保存下来,能让下一次任务少一些重复解释,又保留处理具体问题的余地。仅仅把一段很长的提示词改名为 SKILL.md,还没有解决这些问题。
职责边界:提示词、AGENTS.md、Skill 与工具怎样配合
这些东西经常一起出现,可以按承担的职责理解:
| 组成 | 主要负责什么 | 通常放什么内容 |
|---|---|---|
| 当前提示词 | 说明这次要做的事 | 目标、输入材料、本轮范围和特殊要求 |
| AGENTS.md | 提供持续适用的项目约定 | 仓库命令、代码规范、验证要求等 |
| Skill | 保存一类任务可复用的方法和知识 | 适用场景、判断标准、流程和支持资源 |
| 工具 | 执行具体动作 | 读取文件、运行命令、查询或写入服务 |
| MCP | 连接工具和资源等能力 | 客户端与服务端之间的协议和交互 |
这是帮助理解的分工,不是所有宿主都强制遵守的互斥分类。项目约定可以引用 Skill,Skill 也可以指导 Agent 使用 MCP 提供的工具。
例如,Skill 可以说明查询结果应该怎样核对,但查询动作仍由工具执行;MCP 可以让 Agent 接入外部服务,而怎样组合这些服务完成某类工作,可以写进 Skill。文件中的工具名称也不会自动带来账号、凭据或执行权限。
下面这张官方图把几个部分放在了一起:左侧是 Agent 的配置,右侧是能读取文件、运行程序的环境,Skill 的内容保存在其中的目录里。

图源:Anthropic,Equipping agents for the real world with Agent Skills。这是原文中的虚拟机环境示例;本地文件、工具和 MCP 可以配合使用,不表示每个 Skill 都要求虚拟机或 MCP 服务。
适用范围:什么值得沉淀,什么留在当前任务里
值得写进 Skill 的,通常是会影响执行决策、又能在同类任务中复用的内容。领域规则、容易误读的字段、稳定的交付格式、反复证明有效的处理方法,都可能有价值。
“认真检查结果”过于笼统。“文中引用性能提升时,必须说明比较对象与测试条件;材料不足就保留为待核实结论”,才给出了可操作的判断依据。
临时数据、不断变化的项目状态和一次性的特殊安排,更适合留在当前任务或它们原本的数据源中。把这些内容固化到 Skill,下一次使用时可能反而引入旧信息。能够机械执行、必须精确保证的动作,则应考虑由程序或宿主机制实现,指令负责解释何时调用、输入什么、怎样判断结果。
2 组成结构:SKILL.md 怎样组织指令与资源
入口文件:名称、描述与正文分别承担什么职责
按照 Agent Skills 格式规范,最低结构是一个包含 SKILL.md 的目录。文件开头为 YAML frontmatter,至少有 name 和 description,后面是 Markdown 指令。
下面是从写作任务中提炼的教学片段,用来说明信息分工,并非完整的写作 Skill:
---
name: technical-notes
description: 协助整理中文技术笔记;适用于资料检索、框架讨论和正文撰写,也可局部修改已有稿件。
---
# 技术笔记
新文章先提出核心问题、章节、参考链接与配图计划,确认后写全文。
已有框架批准后直接续写;局部修改按指定范围完成。
区分资料结论与作者判断,不编造个人经历或效果。
起草正文时读取 references/voice.md。
选择或制作配图时读取 references/figures.md。name 用于标识能力;description 让宿主和模型在尚未展开全文时判断它是否适合当前任务。因此描述要先说清“做什么、什么时候用”。只写“帮助处理文档”,很难与翻译、排版、校对等相邻能力区分。
正文再回答选中之后该怎样工作:需要什么输入,哪些判断必须遵守,支持资料在什么时候读取,什么结果算完成。它不需要重新教授模型所有通用知识,重点是补充当前任务缺少、且会改变做法的信息。
支持资源:references、scripts、assets 怎样分工
当入口已经足够说明任务时,单文件就可以工作。需要更多材料时,再增加支持资源:
technical-notes/
├── SKILL.md
├── references/ # 按需读取的知识与规则
│ ├── voice.md
│ └── figures.md
├── scripts/ # 确实需要时使用的辅助程序
│ └── check_image_refs.py
└── assets/ # 用于交付产物的模板或素材
└── article-template.md这是一棵可选结构示意,示例脚本和模板不表示已经实现。各目录承担的工作不同:
| 位置 | 适合保存的内容 | 使用方式 |
|---|---|---|
| SKILL.md | 共通指导、关键约束、资源入口 | 选择 Skill 后读入上下文 |
| references/ | 较长或只在某些情形使用的知识 | 当前步骤需要时再读取 |
| scripts/ | 重复、明确且适合程序执行的处理 | 通过已有执行工具运行,检查输出 |
| assets/ | 模板、图片、样式等产物材料 | 按用途复制、填充或作为格式参考 |
下面的官方 PDF 示例展示了资料拆分:入口保留基本说明,高级参考与表单处理分别放在附加文件里。处理普通 PDF 时,没有必要先展开表单的全部细节。

图源:Anthropic 的 Skill 设计说明。图中的 reference.md、forms.md 是示例文件名,不是所有 Skill 必须具有的结构。
结构取舍:什么时候一个文件就够,什么时候需要拆分
拆分的依据是使用时机。若几段规则总是一起用,而且篇幅很短,放在入口通常最直接;如果不同任务分支需要大量不同材料,分开引用才能减少无关内容。
入口还要说明读取条件。“需要配图时,先读 references/figures.md”比单独罗列几个文件名更清楚。相对路径从 Skill 目录解析,不能假定执行时的工作目录恰好就是安装目录。脚本则应说明参数、依赖、输出位置和结果含义,模板应说明是复制填写还是只作参考。
拆得过细会增加查找和读取次数,引用不清又容易漏读。维护一份 Skill 时,要同时考虑入口是否过长,以及拆出去的内容能不能被找到。目录数量本身没有意义。
有些产品还提供扩展文件。Codex 的 agents/openai.yaml 可以配置界面信息、调用策略和工具依赖,属于产品支持的扩展;开放格式并不要求所有宿主提供同样的配置能力。
3 运行机制:从能力发现到按需加载与执行
发现与激活:宿主和模型各自做什么
文件需要先被宿主发现,才有机会进入任务。宿主可以扫描本地约定目录,也可以通过注册表、API 或内置资源提供 Skill。开放格式规定文件内容,但没有要求所有产品使用同一个安装路径。
发现之后,宿主通常先向模型提供名称、描述等目录信息。模型据此判断是否需要某份指导,再读取对应入口;用户也可以明确指定要用哪一个 Skill。宿主接入指南将发现、目录披露、激活和后续上下文管理分别说明,它们不是一个动作。
以 Codex 为例,当前官方使用说明同时支持显式与隐式调用:CLI、IDE 中可以通过 $skill-name 提及,任务符合描述时也可以由 Codex 选择。隐式选择依赖任务与描述的匹配,不能理解为描述里出现某个词,就一定触发一条固定规则。
具体怎样把入口交给模型,由宿主决定。支持文件读取的环境可以让模型直接读文件,其他环境可以提供激活工具或由程序注入内容。无论走哪条路径,都要把指令实际交给模型,后续才有依据执行。
渐进披露:元数据、正文和资源何时进入上下文
所谓渐进披露,可以顺着三层理解:先知道有哪些能力,再读取被选中能力的完整指导,最后获取当前步骤需要的支持材料。
这三层解决的是同一个问题:任务开始时还不清楚会用到什么,不宜把所有 Skill 的全部内容提前塞进上下文。下面的官方图把一次 PDF 任务中的读取过程展开了。

图源:Anthropic 的上下文加载示例。图中的 Bash 读取方式、文件路径与 system prompt 位置属于该实现示例;这里重点看“摘要 → 入口正文 → 相关资料”的顺序。
图上最初只有各个 Skill 的简短信息。用户提出填写 PDF 的任务后,Claude 读取 PDF Skill 的入口;入口提到表单处理资料,随后再读 forms.md。参考资料之所以拆出去,正是因为它只在这个分支需要。
按需加载也有成本。目录信息仍占空间,被读入的正文和资料同样占上下文;如果入口把所有参考文件都要求提前通读,拆分就失去了作用。应让每次读取服务于当前任务,而不是把一个很长的提示词机械切成多个文件,再一次性全读回来。
长对话中的上下文压缩、已激活内容保留和重复加载控制,则由宿主实现。Skill 可以集中关键约束、留下清楚的资源入口,但文件本身不管理会话内存,也不能保证所有宿主在压缩后采取相同做法。
执行环境:脚本怎样运行,结果怎样交回模型
参考文档主要提供知识,脚本则能承担具体处理。Agent 可以调用已有执行工具,给脚本传入参数,再根据退出状态、输出文件或必要摘要继续工作。执行一个脚本通常不要求先把完整源码读进上下文;排查错误或修改程序时,才可能需要读取源码。
这样可以把适合精确执行的部分留给程序。模型负责判断当前任务需要哪一步、怎样理解结果,程序负责按既定逻辑处理数据。二者的分工仍要求接口清楚:只写“运行检查脚本”,却没有说明检查对象和失败含义,Agent 很难据输出做正确决策。
实际运行还依赖解释器、软件包、网络或服务凭据。Skill 可以写明依赖和使用方法,环境需要另外满足这些条件。使用外部 Skill 时也应读清其指令与脚本;文件格式开放,不代表其中的任意代码都值得直接执行。
4 编写与验证:借助 Codex Skill Creator 提炼工作方法
提炼任务:从真实需求确定输入、输出与边界
编写 Skill 可以从一项已经做过的任务开始:哪些步骤有必要,哪些纠正会在下次继续适用,什么材料帮助模型作出了正确判断。再将这些内容提炼成同类任务的方法,而不是把整段聊天原封不动地保存。
这次整理写作 Skill 时,可以沉淀的是“先讨论框架,再写全文”“不虚构经历”“配图先寻找可复用来源”等方法;本篇文章的具体章节和待修改句子,继续留在文章目录中。两种信息分开,下一篇文章才能复用方法,同时保留自己的主题。
Agent Skills 的编写建议也强调从真实领域材料和实际执行中提取知识。没有这些材料,Creator 容易只能生成“遵守最佳实践、认真处理错误”之类的泛泛要求。
Codex 的 Skill Creator 可以帮助创建或修改这样的文件包。以本次实际读取的 bundled 版本为例,它强调保留用户范围,只加入能改变决策的非显而易见信息,并按任务需要选择支持资源。下面是对这种编写过程的整理,不是每次调用都必须走完的固定流水线。

自绘示意:依据本次使用的 Codex Skill Creator 整理。简单修改可以直接编辑相关规则;只有需要新建骨架时才使用初始化工具。
编写入口:用描述说明适用场景,用正文指导决策
可以先给 Creator 一个明确请求:
$skill-creator 将已经确认的技术文章协作方法整理为写作 Skill。
输入包括主题、笔记、已有草稿或项目材料。
新文章先交章节、资料链接和配图计划,作者确认后再写全文。
局部改稿直接按范围修改,不重新讨论整篇框架。
中文表达和配图细则分开维护;不自动翻译或发布。
已有 yeagerzhao-writing 目录,请就地更新,保留仍有效的资源。这段请求交代了任务、材料、工作方式和范围。Creator 才能据此判断入口需要保存什么,以及哪些细节值得拆出去。若输入只有“做一个很专业的写作 Skill”,生成更多文字也很难补上缺失的判断依据。
描述负责让它在适合的任务中被发现,正文负责让选中之后的执行有据可依。例如,框架是否已确认,会直接影响下一步是讨论还是写全文;这类分支要写清。标题具体有几个字、段落必须几句,则未必需要提前固定。
指导的细致程度也应随任务调整。开放的写作或设计任务需要目标、取舍和必要约束;容易出错的格式转换可以给精确参数和脚本。把所有步骤都锁死,可能让局部修改也绕完整流程;过于抽象,又会让真正重要的边界失效。
组织资源:哪些写成参考,哪些值得做成脚本
本次写作 Skill 的结构可以简化理解为:
yeagerzhao-writing/
├── SKILL.md
├── references/
│ ├── workflow.md # 两阶段协作
│ ├── voice.md # 标题、开头与表达偏好
│ ├── figures.md # 图片选择与绘图方法
│ └── humanizer-op7418.md # 选定的语气编辑快照
└── scripts/
├── lib/drawio.mjs # 将内容模型编译为可编辑图
├── render.ps1 # 调用已有绘图软件导出
└── validate.py # 检查图文件的结构一致性入口说明当前属于构思、正文还是局部修改;详细的开头样例留在语气参考中;只有需要图片时才读配图规则。图的内容与关系仍需判断,模型转换和文件检查则交给已有程序。这里没有为了凑齐结构增加 assets/,因为这份流程暂时不需要独立的产物模板。
Creator 附带的初始化器可以生成目录、入口和部分产品配置,但生成骨架之后,领域内容仍要补全。已有 Skill 更新时,应先检查现有文件和引用,就地修改,不重新初始化覆盖。
产品配置也要单独看。当前 Codex 文档中的 agents/openai.yaml 可声明界面信息、工具依赖与调用策略;例如 allow_implicit_invocation: false 会关闭隐式选择资格,同时保留显式使用。它属于宿主支持的扩展,迁移到其他产品时要核对对方能力,不能仅凭相同目录结构就认为行为一致。
验证与修订:格式通过之后,还要观察实际使用
Creator 的 quick_validate.py 能做基础静态检查,但具体检查项取决于版本。本次本机版本覆盖部分 frontmatter、命名和未完成占位内容;它没有证明所有引用可用、脚本运行正确或模型能完成任务。因此一次“校验通过”只能说明通过了该工具实际执行的检查。
接下来用少量相关任务观察行为。对写作 Skill,可以看新主题是否先给框架,已有批准是否直接续写,局部改稿是否保持范围,以及缺少事实依据时会不会虚构。检查的是结果和边界,不需要要求每次都走完全相同的工具顺序。
如果选错任务,先看描述;已经读取入口却漏掉资料,检查引用时机与路径;脚本处理失败,就定位程序和输入。只有遇到具体缺口,才补对应规则。复杂流程可能需要额外的独立评估,普通文字调整通常做一次回读就够了。
还要注意版本差异:本次使用的 bundled Creator 与公开仓库的版本并不完全相同。公开的 Skill Creator 源码可以帮助理解其组织方法,具体初始化、配置和校验能力仍应以实际使用的版本为准。
5 开源实践:三种值得借鉴的组织方式
判断指导:紧凑入口也能有效
Anthropic 的 frontend-design把重点放在设计决策上:理解主题、受众和用途,再选择字体、配色、布局与动效,并对照需求审视结果。
这类 Skill 的价值在于让设计选择有具体依据。它不需要把前端技术文档全部搬进来,也不需要只为结构完整而添加脚本和参考目录。对于以判断为主、共通指导又能在短入口中表达的任务,单文件可以很合适。
借鉴时应看它怎样组织判断,不能把其中的审美偏好直接应用于所有项目。最终仍要回到使用者的需求和具体内容。
规则索引:大体量知识怎样按需使用
Vercel 的 React best practices则采用另一种结构:入口提供规则分类、影响优先级和索引,独立规则文件解释适用条件,并给出正反代码示例。
这种组织适合条目较多、又需要按问题查阅的知识。处理异步取数问题时,先定位相关规则,再读它的解释;不必为了使用一条规则而提前展开所有内容。规则仍有适用前提,例如并行执行要求操作之间没有必须保留的依赖,不能见到多个 await 就一律改成并发。
它还提供汇编全文,方便一次查阅。Skill 资源中的这类汇编文件,应按入口说明使用;即使文件名也是 AGENTS.md,也不能仅凭名字就认为它等同于当前项目根目录自动适用的约定。
工具衔接:把明确处理交给程序
Anthropic 的 PDF Skill展示了指令、参考资料和工具用法怎样配合。入口给常见处理方法,表单等任务再进入对应说明,具体操作依赖 Python 库、命令行工具或辅助程序。
这里的组织重点是按任务分流,并把输入、处理方式和输出说清。读取表单字段适合程序处理,判断当前应该走哪条路径、字段结果意味着什么,则仍需要指导与推理。
三种结构各有适合的任务:短入口保存判断标准,索引组织大量规则,工具型流程衔接精确处理。它们没有统一的理想目录。整理自己的 Skill 时,先看反复需要补充的知识和实际执行中的缺口,再决定该留下什么,通常比先设计一套庞大结构更容易维护。
本文依据 2026 年 11 月 16 日查阅的公开规范、官方资料与本机 bundled Creator 整理。涉及具体产品行为的部分,以对应宿主和版本为边界。
参考资料:规范、实现与原始说明
- Agent Skills:格式规范
- Agent Skills:为 Agent 添加 Skills 支持
- Agent Skills:编写建议
- Anthropic:Equipping agents for the real world with Agent Skills
- OpenAI:Build skills
- OpenAI:Skill Creator
- Anthropic:frontend-design
- Vercel:React best practices
- Anthropic:PDF Skill
- Simon Willison:Claude Skills are awesome, maybe a bigger deal than MCP,可补充阅读其对简单文件设计与执行环境的理解;其中的前景判断属于作者观点。

