Agent Skill 开发规范：从 SKILL.md 到可维护的工程资产

AI让代码和文档生成更快，却容易把Skill做成“大而全”：职责混杂、资料堆积，最终拖累维护效率和上下文成本。Skill的关键不在内容多，而在边界清晰、职责明确、按需加载。

发表于 2026/08/24

作者羊羽

42 分钟阅读

1. 目标与适用范围

这份规范并非官方标准，而是我在开发和迭代Skill的过程中，结合软件工程经验逐步整理出来的一套个人实践。我把它记录成博客，方便自己在后续开发中引用，也便于公开分享、讨论和修正。

刚开始开发Skill时，很容易把它理解成一个目录加一份SKILL.md。真正投入长期使用后，才会发现“能跑”只是起点。一个Skill能否被正确发现、稳定执行、按需加载和持续维护，才是更值得关注的问题。

因此，本文将Agent Skill视为一份面向Agent的可复用能力契约，并围绕能力发现、执行流程、工具调用、资源加载和结果验证展开。

本规范适用于使用SKILL.md描述能力的Agent运行时和Skill开发者，重点覆盖：

Skill目录与文件组织；
元数据、触发条件和调用边界；
Claude Code与Codex的兼容设计；
写入、只读、重试和幂等；
references、scripts和assets的渐进式加载；
发布前检查和运行时验证。

本规范不规定具体业务流程，也不要求所有Skill使用相同的工具、脚本或外部服务。

2. 基本原则

能力优先：Skill应描述用户能获得的能力和适用场景，不应主要用内部脚本、目录路径或后端接口来定义。
共同契约优先：SKILL.md中的name、description和正文是跨运行时的共同基线。某个运行时专用的字段和配置只能作为适配层，不能替代共同契约。
边界先于自动化：Skill必须明确适用场景、不适用场景、可能产生的副作用，以及哪些操作需要用户确认。对于具有外部副作用的能力，应优先保证可控和可核验，而不是扩大自动化范围。
证据优先：成功、失败、重试和回执都应以工具或服务端的实际结果为依据。不能仅凭命令已经结束、猜测出的URL或模型推断，就把结果写成成功。
渐进式加载：核心指令保持短小；详细资料、示例和实现逻辑按需放入references/和scripts/，避免无关内容长期占用上下文。

3. 源码归属与目录结构

3.1 单个Skill的结构

skill-name/
├── SKILL.md              # 必需：元数据与核心指令
├── agents/openai.yaml    # 可选：Codex侧界面与策略适配
├── scripts/              # 可选：可执行脚本
├── references/           # 可选：按需读取的详细资料
├── assets/               # 可选：模板、图片等静态资源
└── LICENSE.txt           # 可选：许可证

目录名必须与Skill的name一致。只在确有复用价值时增加脚本、引用资料或静态资源，不要为尚未出现的需求预建目录。

Skill配套物料应遵循高内聚、低耦合等基本软件工程原则，并确保目录和文件的职责清晰：

scripts/按领域职责拆分为独立的子脚本或模块，每个文件完成一项可独立理解和测试的工作，入口脚本只负责编排；
references/按主题或使用阶段拆分为独立的Markdown文件，每个文件聚焦一个知识单元，并由SKILL.md说明何时读取；
关系紧密、总是一起变化的内容可以放在同一文件中，不按行数机械拆分。

AI可以快速生成代码和文档，但Skill开发不能因此走向“大而全”。把不同职责堆进同一个脚本，会增加测试、复用和修改的难度；把所有资料堆进同一个文档，则会在加载时引入大量无关内容，增加上下文成本。

3.2 与系统源码保持内聚

如果一个Skill与某个系统的能力、领域模型、接口或研发流程强相关，它的指令、脚本、参考资料和测试就应优先维护在该系统的源码仓库中，与系统代码一起评审和演进。

同仓维护可以保证：

Skill引用的接口、命令和目录结构与源码版本同步；
系统变更时可以在同一Code Review中更新代码、文档、Skill和测试；
Skill的负责人、发布节奏和问题归属与系统本身一致；
安装到Agent目录的副本只是分发产物，系统源码仓库仍是唯一事实源。

只有当一个Skill服务于多个生命周期彼此独立的系统，并且已经形成稳定的公共能力时，才考虑拆成独立仓库。不要只为潜在的复用需求提前分仓。

3.3 系统仓库中的两类Skill

同一个系统源码仓库中，通常会同时存在两类Skill：

类型	服务对象	典型内容	目录建议	分发策略
系统能力Skill	系统使用者或其他Agent	系统能力说明、调用流程、SDK式操作和领域约束	`skills/`或仓库约定的公开Skill目录	可通过`npx skills`选择和安装
研发流程Skill	系统维护者	开发、测试、内容治理、发布、CI/CD和仓库维护流程	`.agents/skills/`、`.claude/skills/`等项目级目录	默认仅在仓库内使用，必要时标记为内部Skill

两类Skill可以共享同一个源码仓库，但不能混淆受众和生命周期：

系统能力Skill类似系统的SDK，描述系统对使用者稳定提供的能力，应随对外契约变更同步迭代；
研发流程Skill属于仓库工程设施，描述如何开发、验证和发布该系统，应随工程流程变更同步迭代；
研发流程Skill不得因为与系统能力Skill同仓，就被默认当成公开能力分发；
系统能力Skill也不应依赖某个维护者本机的.claude/、.agents/或私有环境配置。

推荐布局：

system-repo/
├── src/                         # 系统源码
├── skills/                      # 系统提供的能力Skill
│   └── system-capability/
│       └── SKILL.md
├── .agents/skills/              # 仓库研发流程Skill
│   └── repository-workflow/
│       └── SKILL.md
└── tests/

本规范所说的“内部Skill”，是指面向仓库维护者和研发流程的Skill。它不属于系统向使用者提供的稳定能力。

无论是否参与分发，内部Skill都必须遵守最小权限、副作用确认和敏感信息保护要求。

4. `SKILL.md`规范

SKILL.md由Front Matter和Markdown正文两部分组成。Front Matter负责能力发现、描述和运行时控制，正文负责执行流程、输入处理、边界和验证。Front Matter字段与正文中的动态占位符属于不同机制，必须分别设计和验证。

4.1 Front Matter

最小配置只需要name和description：

  
---
name: skill-name
description: 描述能力和触发场景
---

Agent Skills规范定义的字段如下：

参数	作用	要求
`name`	定义Skill名称	必填；小写字母加连字符；与目录名一致
`description`	说明能力和触发场景	必填；写清“能做什么”和“什么时候使用”，不暴露实现细节
`license`	声明许可证	可选；按发布和分发要求填写
`compatibility`	声明环境依赖	可选；只写真实存在的依赖
`metadata`	承载自定义元数据	可选；不得把运行时开关藏在其中
`allowed-tools`	声明允许使用的工具	可选、实验性；使用前确认目标运行时支持

这些字段只描述各运行时都能理解的共同语义。Claude Code和Codex的专用控制字段属于适配配置，不能混入共同契约。

4.2 正文内容

正文只保留每次执行都要对照的规则，可以按三层组织：

定位层：目标、适用场景、不适用场景和核心边界；
执行层：输入来源、默认值、不可推断内容、执行顺序、工具边界、失败处理和结果核验；
速查层：必要命令、输出格式、关键限制和资源索引。

不要重复Skill名称、调用命令、元数据或相同的触发限制。详细参数、背景资料和示例放入references/，正文只说明何时读取。除非明确只支持某个运行时，正文默认按静态Markdown编写。

4.3 内容插值与动态变量

4.3.1 跨运行时基线

Agent Skills规范只规定Front Matter和Markdown正文结构，没有定义正文插值语法。$ARGUMENTS、位置参数、环境变量替换和命令注入都不是Claude Code与Codex之间的共同契约。

面向多个运行时的Skill应遵守以下要求：

即使没有任何占位符，正文也必须足以让Agent理解任务，并直接说明“从当前用户请求中提取目标、范围和约束”；
缺少必需输入时，按照正文约定从上下文获取或向用户确认，不假设运行时会自动补齐；
只有目标运行时的官方文档明确支持时，才使用动态变量，并在compatibility或项目文档中声明运行时要求；
同一个Skill需要跨运行时分发时，优先保留静态正文。确需动态插值时，再为不同运行时维护薄适配层并分别测试。

4.3.2 Claude Code

Claude Code会在Skill正文加载前执行字符串替换，常用变量如下：

变量	含义与使用边界
`$ARGUMENTS`	调用Skill时传入的完整参数；正文未使用它时，Claude Code会在末尾追加`ARGUMENTS: <value>`
`$ARGUMENTS[N]`	按从0开始的下标读取参数，例如`$ARGUMENTS[0]`表示第一个参数
`$N`	`$ARGUMENTS[N]`的简写；`$0`是第一个参数，`$1`是第二个参数
`$name`	`arguments` Front Matter字段中声明的命名位置参数；名称按声明顺序映射到参数位置
`${CLAUDE_SESSION_ID}`	当前会话ID，适合日志关联和会话级文件命名
`${CLAUDE_EFFORT}`	当前effort等级，用于确有必要的指令强度适配
`${CLAUDE_SKILL_DIR}`	当前Skill目录，适合稳定引用Skill内的脚本和资源
`${CLAUDE_PROJECT_DIR}`	项目根目录；需要Claude Code 2.1.196及以上版本
`${CLAUDE_PLUGIN_ROOT}`	插件安装目录，仅在插件Skill中替换
`${CLAUDE_PLUGIN_DATA}`	插件持久数据目录，仅在插件Skill中替换

需要固定参数结构时，可以配合Claude Code专用Front Matter字段：

  
---
argument-hint: "[issue] [branch]"
arguments: [issue, branch]
---

此时，正文中的$issue和$branch仍按位置映射，并不是任意键值变量。单个参数包含空格时，应按Shell风格加引号。

位置参数缺失时，占位符会原样保留；命名参数缺失时，占位符会替换为空字符串。如果正文需要显示$1.00等字面量，应写成\$1.00。

这些字段和替换行为属于Claude Code扩展，不适用于claude.ai上传或Skills API等只接受Agent Skills标准字段的入口。

4.3.3 Codex：从用户请求读取输入

在Codex中，用户可以在请求开头使用$skill-name选择Skill，后面的内容仍然是普通的用户请求：

$code-review 检查src/order.js中的并发问题

这里的$code-review只负责选择Skill，不会成为SKILL.md正文中的变量。Codex会同时读取Skill正文和当前用户请求，因此正文应直接说明如何从请求中获取输入：

# 不推荐
检查$ARGUMENTS中的代码。

# 推荐
从当前用户请求中获取检查目标和关注点；缺少必要信息时先确认。

当前Codex Skills不提供$ARGUMENTS、$N或命名参数等正文插值能力。旧版Custom Prompts虽然支持这些占位符，但它与Skills属于两套机制。迁移时，必须改写成上面的输入提取规则。

4.4 资源路径与Skill依赖

Skill内部资源必须使用相对于Skill根目录的路径：

scripts/index.js
references/auth.md
assets/template.json

一个Skill依赖另一个Skill时，只引用对方Front Matter中的name。具体的发现和加载由运行时负责。例如：

使用`task-management` Skill创建任务。

不得使用/Users/name/.agents/skills/task-management/SKILL.md、../task-management/SKILL.md或其他固定安装路径引用依赖。不同用户、项目和Agent的Skill安装位置并不一致，依赖固定路径的Skill无法可靠分发和迁移。

运行时找不到依赖Skill时，应明确提示安装或启用对应name的Skill，不得猜测本机路径或直接读取某个安装副本。

5. 运行时控制与兼容

Claude Code和Codex都读取SKILL.md，但调用方式和专用配置不同：

项目	Claude Code	Codex	兼容要求
共同内容	`name`、`description`、正文	`name`、`description`、正文	必须独立成立
显式调用	通常使用`/skill-name`	通常使用`$skill-name`	正文不依赖某一端语法
禁止隐式调用	`disable-model-invocation: true`	`policy.allow_implicit_invocation: false`	两端分别配置和验证
用户可调用	`user-invocable: true`	由Skill发现和显式调用机制决定	不把单端字段当成共同开关
UI信息	不依赖`agents/openai.yaml`	可在`agents/openai.yaml`中配置	UI字段不承载业务规则

5.1 Claude Code参数

Claude Code支持在SKILL.md中声明调用方式：

  
---
name: example-skill
description: 用户明确要求整理技术资料时使用。
argument-hint: "[topic] [source]"
arguments: [topic, source]
disable-model-invocation: true
user-invocable: true
---

argument-hint：在自动补全中提示参数形式，不负责校验参数；
arguments：为正文中的命名位置参数声明名称，按顺序与调用参数对应；
disable-model-invocation: true：禁止Claude Code根据语义自动加载；
user-invocable: true：允许用户通过Claude Code的显式调用入口使用；
这些字段只说明Claude Code的行为，不能作为Codex侧的参数或开关。

5.2 Codex参数

Codex的界面信息和调用策略通常放在agents/openai.yaml：

  
interface:
  display_name: "示例能力"
  short_description: "整理技术资料"
  default_prompt: "使用 $example-skill 整理这份资料。"

policy:
  allow_implicit_invocation: false

interface.display_name：界面展示名；
interface.short_description：短描述；
interface.default_prompt：显式调用时使用的默认提示；
policy.allow_implicit_invocation: false：禁止Codex隐式注入，要求用户显式调用。

agents/openai.yaml是Codex适配层，不应承载核心业务规则。即使缺少该文件，Agent仍应能仅凭SKILL.md理解Skill的能力和边界。

5.3 流程参数不属于Front Matter

确认策略、目标路径、重试次数、幂等键、输出格式等属于执行流程，应写在正文或脚本参数说明中，而不是随意扩展Front Matter。例如：

写入前先检查目标是否已有同一结果。超时或空输出时只读核验，不直接重试。

三者的职责由此分开：元数据负责判断“是否相关”，正文说明“如何正确执行”，脚本负责具体实现。

对于只能由用户明确触发的Skill，应同时配置对应运行时的显式调用策略。description中的“用户明确要求时使用”只能作为发现提示，不能代替运行时开关。

新增或使用单端字段前，应查阅对应版本的解析器或官方文档。不能因为本地校验脚本接受某字段，就断言所有运行时都支持它。

6. 执行边界

Skill应根据是否产生外部副作用采用相应约束，不要给简单能力套用无关流程。

6.1 写入型Skill

写入文件、任务、消息、文档、数据库或其他外部资源时，必须遵守以下要求：

从用户请求和已确认上下文获取目标、身份和内容，不从未授权的数据源自动采集或补全；
写入前检查目标现状、认证和必要字段，避免重复写入；
同一事项只写入一个目标系统，除非用户明确要求同步到多个系统；
针对一个完整意图，只发起一次有效写入，并使用服务端返回的ID、URL或状态核验结果；
超时、空输出或结果不明确时，先只读核验，不直接重试。

用户已明确授权且输入无歧义时，不重复确认。存在不可逆操作、目标不明确或需要实质改写时，写入前必须完成一次完整确认。

6.2 只读与解释型Skill

只读和解释型Skill应守住证据边界：

优先使用真实源码、测试、配置或官方资料，区分事实、文档说明、推断和未知；
先建立必要的整体认识，再按问题范围下钻，不默认遍历整个仓库；
用户只要求理解时保持只读，不修改文件、分支或外部状态；
整理知识时区分原始材料、个人理解和可复用结论。

7. 脚本开发规范

7.1 技术栈与依赖

Skill自带脚本必须使用Node.js实现，不使用Python或其他需要额外安装运行时的语言。

主流AI开发工具大多基于Node.js构建，其运行环境通常已经预装Node.js。统一使用Node.js，可以避免额外引入解释器、虚拟环境和依赖管理工具，提高Skill在不同Agent和开发环境中的可移植性。

脚本使用.js或.mjs文件，并通过node scripts/<script-name>执行；
优先使用Node.js标准库，只有标准库无法合理满足需求时才增加第三方依赖；
引入第三方依赖时，必须提交对应的package.json和锁文件，并说明安装方式；
不假设环境已安装python、uv、pip、Ruby、Go或其他额外工具链；
确需调用系统命令时，应在compatibility或正文中声明依赖，并在脚本执行前检查。

7.2 设计与执行

保持入口轻薄：入口脚本只负责编排，不承载全部实现。领域逻辑应按职责拆到独立子脚本或模块，便于单独测试、复用和修改。
封装高摩擦IO：稳定且重复的文件读写、路径处理、接口调用和Git操作应封装成脚本，减少模型临场操作带来的授权次数和出错风险。SKILL.md只保留输入、边界和验收要求。
让前置检查靠近执行：环境变量、认证状态、目标路径和目录类型等条件，应由执行对应操作的脚本就近检查，并返回可操作的错误信息。不要依赖模型临场编写Shell，也不要自动创建用户未确认的资源。
保证参数真实生效：脚本声明的参数必须参与执行逻辑。建议提供--help，并保证帮助文本中的路径、参数名与SKILL.md一致。
保留可观察的错误：错误消息应说明原因和下一步操作。批量处理时，可以按输入分别报告结果；涉及写入且结果不明确时，必须停止重试并先只读核验。
保护凭据和日志：凭据、私钥、访问令牌和疑似敏感字段不得写入仓库、命令回执或普通日志。日志只保留排查所需的最小信息。

8. 注意事项与实践技巧

以下做法来自实际迭代经验，不要求每个Skill都采用。只有在能降低复杂度或减少错误时才引入，不要为了形式增加额外机制。

用阶段产物控制复杂工作流：复杂能力可以拆成四个阶段：分析与澄清、形成方案或草案、执行、验证。每一阶段的产物都作为下一阶段的输入。不要用一个大Prompt同时处理需求理解、方案设计和写入执行。
先完整阅读，再提炼规则：为已有流程提炼Skill时，应先完整梳理相关材料、调用链和例外情况，再抽象其中稳定的规律。不要把局部片段中的一次性措辞、偶然结构或临时workaround写成长期规范。
迭代时优先删改：主动删除重复说明、过时命令、未经验证的结论、相互矛盾的边界，以及无助于执行的背景。对AI规则资产来说，一条错误规则往往比规则缺失更危险。
用运行时事实校验静态配置：文件存在、字段被解析或命令未报错，都不能单独证明Skill已经生效。至少要验证Skill能否被发现和触发、正文是否加载、工具是否注册，以及写入结果能否回读。涉及版本差异时，还要先核对实际版本。

9. 分发与安装惯例

SKILL.md解决的是“安装后如何被Agent理解和执行”，不负责Skill的发现、选择和分发。

本文所说的Skill“分发和安装”，是指使用Vercel Labs的skills CLI，从仓库中发现并选择Skill，再将其安装到Claude Code、Codex等目标Agent。该工具通常通过npx skills调用。

skills CLI属于Skill的包管理和安装层，不是Agent Skills规范，也不是Agent运行时。它已经是当前开放生态中事实上的默认分发入口之一。

以GitHub仓库为例，skills负责把仓库中的Skill安装到本地Agent环境：

flowchart LR
    G[GitHub仓库<br/>owner/repo] --> C[npx skills add owner/repo]
    C --> S[发现并选择Skill]
    S --> A[选择目标Agent]
    A --> I{安装范围}
    I -->|默认| P[项目级Skill目录]
    I -->|--global| U[用户级Skill目录]
    P --> M[链接或--copy复制]
    U --> M
    M --> R[Claude Code或Codex<br/>发现并加载Skill]

skills只负责完成本地安装。Skill的触发、加载和执行仍由Claude Code、Codex等目标Agent负责。

这里要区分四类配置：

配置类型	负责内容	典型控制项
Skill契约	能力、触发条件、执行边界和结果验证	`name`、`description`、正文
分发管理	搜索、选择、安装范围和更新	`find`、`add`、`update`、`remove`
运行时适配	安装到哪些Agent、如何展示和是否允许隐式调用	`--agent`、`agents/openai.yaml`
安装方式	选择项目级或全局安装，以及链接或复制	`--global`、`--copy`

分发和安装参数不能代替Skill正文中的安全边界。比如，-y只表示跳过安装确认，并不表示可以跳过Skill执行时的用户确认。--global只会改变安装作用域，也不代表Skill拥有更高的业务权限。

9.1 常用命令

  
# 搜索公开Skill
npx skills find <关键词>

# 查看仓库中可安装的Skill，不执行安装
npx skills add owner/repo --list

# 安装指定Skill到指定Agent
npx skills add owner/repo --skill skill-name --agent claude-code

# 安装到用户级目录，并跳过安装确认，适合已审查的自动化环境
npx skills add owner/repo --global --agent codex --yes

# 更新已安装Skill
npx skills update skill-name

# 移除指定Agent上的Skill
npx skills remove --agent codex --skill skill-name

9.2 安装控制项

常见控制项可以按五个维度理解：

来源和选择：仓库、URL、--list、--skill、--all；
目标Agent：--agent，必要时明确安装到哪些Agent，不默认扩散到全部环境；
作用域：--global控制用户级安装，否则通常是项目级安装；
确认策略：--yes适合已审查、可重复的CI流程，不应成为默认安全策略；
物化方式：--copy将文件复制到目标目录，默认链接方式则更适合开发阶段同步源目录变更。

部分版本还提供递归搜索、子Agent目标或安装事件元数据等参数。使用前应以当前CLI的--help和版本文档为准，不要把某个版本的参数列表写成Agent Skills标准。

npx skills不会根据Skill内容判断它属于“系统能力”还是“研发流程”。这一区分必须通过源码仓库的目录和文档来表达。

9.3 内部Skill过滤技巧

Vercel Labs Skills CLI支持使用metadata.internal控制发现范围：

  
---
name: repository-workflow
description: 维护当前仓库研发流程时使用。
metadata:
  internal: true
---

当前CLI默认过滤metadata.internal: true的Skill。需要检查或安装内部Skill时，可以通过环境变量显式开启：

  
INSTALL_INTERNAL_SKILLS=1 npx skills add owner/repo --list
INSTALL_INTERNAL_SKILLS=1 npx skills add owner/repo --skill repository-workflow

metadata.internal是Skills CLI的扩展字段，只表达发现和分发意图。它既不是Agent Skills核心规范，也不能用于控制运行时权限。内部Skill的显式安装方式属于CLI实现，在自动化流程中使用前必须核对当前版本。

9.4 发布者需要注意的事项

仓库入口、Skill目录名和SKILL.md中的name应保持一致，避免同一个Skill在安装后出现不同标识。
公开分发的description应便于搜索，但不能把内部路径、凭据、组织名称或未公开后端写进去。
无论采用项目级还是全局级安装，都应明确Skill文件属于哪个项目、由谁维护，以及从哪里更新。
链接安装适合开发迭代，复制安装更适合发布快照；两者的更新和排障方式不同，应在项目文档中说明。
find搜到Skill不等于它可信。安装前应检查来源、代码、脚本、权限和副作用，尤其是包含scripts/或会访问外部系统的Skill。

9.5 更新与回滚

更新Skill前应记录来源、版本或提交标识。开发阶段可以使用链接方式观察源目录变化；发布或排障时应能切换到确定版本的复制快照。

当更新后出现触发、解析或执行异常，优先比较以下内容：

SKILL.md的Front Matter和正文差异；
安装目录是链接还是复制；
分发工具的lock记录与实际目录是否一致；
目标Agent是否读取了新的安装路径；
运行时版本是否发生变化。

不要只因为安装命令成功，就断言Skill已经被目标Agent加载；安装成功、被发现、被触发和执行成功是四个不同的验证点。

10. 发布前评审清单

name与目录名一致，格式合法
与系统强相关的Skill源码、脚本和测试维护在系统源码仓库内
已区分系统能力Skill与研发流程Skill，并明确各自受众和分发策略
description包含能力和触发场景，不包含实现细节
正文明确适用边界、不适用场景和失败处理
定位层、执行层和速查层职责清楚
写入型Skill具备写入前检查、单次写入、结果核验和防重复策略
目标、身份、凭据和外部标识没有被臆测
Claude Code和Codex的单端配置没有被误当成共同规范
内部资源使用相对路径，跨Skill依赖只引用对方的name
Skill自带脚本统一使用Node.js，不依赖Python或其他额外运行时
scripts/和references/按领域职责拆分，没有堆积无关内容的大文件
脚本参数真实生效，帮助文本与正文一致
SKILL.md保持短小，详细内容按需放入references/
已在目标运行时验证显式触发、隐式触发和失败分支
对有副作用的操作验证了授权、幂等和服务端回执

11. 总结

归根结底，Skill开发不只是写完一份Markdown，而是要将一项能力作为可发现、可执行、可验证、可演进的工程资产持续维护。这份规范提供的是一组可复用的工程边界，并不要求把所有Skill做成同一种样子。具体实现仍应结合运行时和使用场景持续修正。

12. 参考

AI , Agent

本文由作者按照 CC BY 4.0 进行授权