SKILL.md 模式

SKILL.md 通过渐进披露、结构化表达和模块化设计，实现了 AI 能力的动态扩展和高效管理。它结合了自然语言指导和可执行脚本的优势，让开发者以声明式方式定义 AI 技能，突破传统上下文窗口的限制。

什么是 SKILL.md：设计理念与实现详解

SKILL.md 本质上是一些组织良好的“技能包”，每个技能包就是一个目录文件夹，包含特定任务所需的指令、脚本和资源。通过这些技能包，Claude 等通用 AI 可以动态加载特定领域的专业知识，从而在执行特定任务时表现得更专业、更可靠。

一个技能包的核心是其中的 SKILL.md 文件。该文件以 YAML frontmatter 开头，包含技能名称和描述两个必需字段。下面是一个最简的技能文件结构示例：

在实际开发中，建议参考如下 Markdown 结构：

---
name: my-skill-name
description: 用一句话清晰描述此技能的作用和何时使用
---

# My Skill Name

这里编写当技能激活时，Claude 应遵循的具体指令...

## Examples
- 示例用法 1
- 示例用法 2

## Guidelines
- 指导原则 1
- 指导原则 2

上述 YAML 元数据（技能的名称和描述）是 SKILL.md“渐进披露”设计的第一级信息。在智能体启动时，Claude 的 system prompt 会预先加载每个已安装技能的名称和描述。这相当于为 AI 提供了一份“技能目录”或“内容表”。每个技能的描述用几句话概括了技能能做什么、何时适用。这一机制极为高效——每个技能在未被实际使用前只占用几十个 token 的上下文。这些元数据就像一本手册的目录，让模型知道有哪些技能可用以及大致用途，但不会一下子把整本手册读入记忆。

在对话过程中出现某个任务时，Claude 判断某个技能可能相关，会主动加载该技能的完整内容，即读取完整的 SKILL.md 正文（这被视为第二级信息披露）。SKILL.md 正文中可以详述该任务的步骤、策略、示例、指南等，将人类的程序化知识传授给 AI。例如，在 Anthropic 官方提供的 PDF 处理技能中，pdf/SKILL.md 包含了关于如何提取 PDF 文本、填充表单域等指导，而 Claude 只有在需要处理 PDF 表单时才会真正读取这些详细说明。

如果单个 SKILL.md 文件内容过于庞大，或者其中有某些指导只在特定场景下才用得上，Skills 允许技能包内含有多个子文件。SKILL.md 可以通过 Markdown 链接引用这些附加文件。当 Claude 发现需要更细节的说明时，才会按需打开相应文件（这构成第三级及后续的渐进披露）。例如，在前述 PDF 技能中，核心步骤写在 SKILL.md，而关于 PDF 表单填充的具体操作被放入 forms.md 并在需要时才加载。通过将少用的细节拆分到附加文件，Skill 作者可以保持核心说明精炼，同时相信模型会在恰当时机自行查阅附加内容。

这种多层次的上下文提供策略体现了 SKILL.md 的核心设计理念——渐进披露（progressive disclosure）。它就像一本组织良好的手册：一开始只有目录（技能名称和描述），需要时才翻开相应章节（SKILL.md 正文），更细的内容则在附录里按需查阅。由此，技能可以打包任意多的信息而不怕超出上下文窗口，因为模型不会一次性把所有内容塞进对话，而是利用自己的“工具使用”能力，在需要时自己去“阅读”文件系统中的内容。换句话说，在具备文件系统和代码执行工具的前提下，技能所能提供的上下文量实际上不受上下文窗口限制。

除了指导说明，技能还可以包含可执行代码。Anthropic 允许在技能包目录中附带脚本（如 Python 文件），Claude 可以在需要时将其当作工具执行。这种设计背后的思想是：LLM 虽然强大，但有些操作用传统代码更高效、确定性更强。例如，让 LLM 按 token 排序一大串数字，远不如执行一个排序算法来得快；又或者在 PDF 表单中提取字段，与其让模型逐字“想象”提取，不如运行脚本直接解析。Anthropic 官方举例，在 PDF 技能里附带了一个 Python 脚本，可以读取 PDF 文件并提取其中的表单字段。Claude 无需将整个 PDF 文件或脚本内容加载进上下文就能调用这个脚本，获取结构化结果并返回，使工作流程高效且结果可重复。更妙的是，技能脚本还能执行一些验证/约束。例如 Slack GIF 制作技能里提供了一个函数用于检查生成的 GIF 大小是否符合 Slack 要求，如果初次生成超标，Claude 可以据此调整参数重新生成。通过将部分任务外包给代码执行，Skills 结合了 LLM 的灵活性和传统编程的可靠性。

需要强调，Skills 的威力很大程度上依赖于模型具备一个真实的计算环境。Claude 的实现（特别是在 Claude Code 模式中）提供了类似沙箱的执行环境，允许模型读写文件、运行代码，这与 OpenAI 的 Code Interpreter（代码助手）思路类似。Anthropic 工程团队指出，安全的代码执行环境是 Skills 得以发挥作用的关键前提，也是与过去一些 LLM 扩展方案（如 MCP、ChatGPT Plugins）的最大区别之一。当然，这对安全提出了更高要求：需要充分沙箱隔离，防止模型借助代码执行做出越权行为或遭受提示注入攻击。Anthropic 在博客中也坦承，“safe”环境仍需不断打磨，以便既解锁技能的潜力，又将风险控制在可接受范围。

综上，SKILL.md 的实现可以概括为：用文件系统承载知识，用模型自己去检索知识。相比传统 prompt 工程反复堆砌海量提示，Skills 将人类的程序化知识以结构化方式外置，并利用 LLM 善于工具使用的能力，按需调入所需的信息。这体现了一种工程上的极简哲学：把复杂性留给模型和环境，开发者只需“把知识写清楚”即可。正如 Simon Willison 所言，这种方法“更贴近 LLM 的原始精神：抛给它一些文本，让模型自己 figure it out”。

Skills 的工程抽象理念：能力的结构化表达

SKILL.md 所体现的工程抽象理念主要包括以下几点：

• 技能 vs 工具：技能更偏向知识和流程的封装，工具更偏向动作和函数的封装。前者利用 LLM 理解自然语言的能力，后者利用程序的确定性执行能力。Skills 实际上将两者结合——用文档教模型“如何做”，用脚本提供“做到这件事的工具”。从使用体验看，调用技能比调用工具更加自动化和灵活：模型自己决定何时需要技能并加载相应内容，而调用工具通常需要模型明确知道某个函数适用。Skills 降低了扩展 AI 能力的门槛（不要求懂编程接口，只要能写明步骤即可）。
• 结构化 vs 非结构化：传统上，我们给 AI 加知识可能就是在 prompt 里追加一大段说明，这其实是非结构化的方式。而 Skills 提供了 YAML 元数据、Markdown 分章节、可选文件链接等，这些都是结构化表达的体现。结构化带来的好处是：AI 可以基于结构来有选择地阅读（如先看描述再决定看正文），也方便技能的检索和管理（元数据可以作为索引）。同时结构化并没有损失灵活性——Markdown 文本对模型来说依然是自然语言提示，保持了极大的通用性。
• 能力模块化与复用：Skills 推崇将特定能力打包成易于分享的模块。这就像软件开发从 monolith 走向 microservice，那 AI 能力开发也从定制 prompt 走向可插拔的技能模块。模块化使得重复造轮子的情况减少：比如每个人都教自己的 AI 怎么处理 Excel，不如大家共享一个 Excel 技能模板。这与 Cursor Rules 社区出现“Awesome Cursor Rules”库、Claude 社区出现各种技能集合是类似的动因。长期看，行业标准可能会逐渐形成（就像 AGENTS.md 之于代码代理）。Anthropic 的做法无疑是朝这个方向迈出了一步。
• 隐式编程：Skills 强调“把人类的程序性知识教给 AI”。这与传统编程的区别在于，我们并非写代码调用 API 让 AI 干活，而是写下规则让 AI 自己去执行。某种程度上，这是一种“隐式的编程”：程序不在计算机里跑，而是在模型的思维中跑。这对开发者提出了新要求——写技能既要给人看得懂，也要让 AI 理解并执行得好。这有点像写一份面向 AI 的 SOP（标准作业程序），需要清晰、严谨，同时考虑 AI 可能的误解点。如何写好技能说明正在成为一种新的技巧，有人就强调用 SOP 方法打造可靠的 Skills。这也是 SKILL.md 这种抽象的独特之处：它处在自然语言和代码的交汇点，让非程序员也能“编程”AI。

SKILL.md 文件结构

技能包格式

每个 Agent Skill 技能包是一个目录文件夹，核心是其中的 SKILL.md 文件。文件以 YAML frontmatter 开头，包含必需字段：

• name: 技能名称
• description: 简短描述技能作用和适用场景

基本结构示例

以下为技能包 Markdown 文件的基本结构：

---
name: my-skill-name
description: 用一句话清晰描述此技能的作用和何时使用
---

# My Skill Name

这里编写当技能激活时，Claude 应遵循的具体指令...

## Examples
- 示例用法 1
- 示例用法 2

## Guidelines
- 指导原则 1
- 指导原则 2

技能包目录结构

一个完整的技能包可能包含如下内容：

skill-name/
├── SKILL.md          # 核心技能文件
├── script.py         # 可执行脚本（可选）
├── forms.md          # 附加说明文件（可选）
└── resources/        # 资源文件夹（可选）

SKILL.md 的优势

渐进披露与高效上下文管理

SKILL.md 利用 YAML 元数据提供技能目录，避免一次性加载过多信息。按需加载技能内容，有效突破上下文窗口限制，并支持多层次信息披露，从描述到详细指导逐步展开。

结构化知识表达

结合 YAML 元数据和 Markdown 文本，实现知识的结构化组织，便于技能的检索、管理和版本控制，同时支持技能模块的复用和分享。

灵活性和自动化

模型自主决定何时加载技能，无需手动指定。结合可执行脚本，提供确定性操作能力，支持复杂任务的模块化分解和执行。

SKILL.md 的实施策略

技能分类

下表展示了 SKILL.md 的分类体系：

技能评估

下表总结了常见的技能评估方法：

SKILL.md 的最佳实践

以下表格总结了编写原则与维护策略：

SKILL.md 在开发中的应用

下表展示了 SKILL.md 在项目配置、团队协作与持续改进中的应用场景：

与其他规范的配合

下表说明了 SKILL.md 与其他规范的集成方式：

总结

SKILL.md 通过渐进披露、结构化表达和模块化设计，实现了 AI 能力的动态扩展和高效管理。它结合了自然语言指导和可执行脚本的优势，让开发者能够以声明式方式定义 AI 技能，同时突破传统上下文窗口的限制。这种设计不仅提升了 AI 助手的专业性和可靠性，还为 AI 能力开发提供了新的工程抽象理念。