还在手搓 Agent ？SKILL.md 正在让一切变得不同

你也在“养虾”吗？OpenClaw确实让AI从“对话”变成了“执行”——它能操控你的电脑、管理你的文件、收发消息、执行shell命令。但问题来了：你给它权限，它却不知道怎么干活。就像你招了一个执行力爆表的实习生，但他需要你手把手教他每一步怎么走。传统的做法是写复杂的Agent代码，动辄几百行，调试到崩溃。

直到我发现，OpenClaw生态里一个被严重低估的玩法：SKILL.md。它不是代码，而是AI的“操作说明书”。当你用OpenClaw给AI打开了一扇门，SKILL.md就是告诉它门后那间房间里，每样东西该怎么用。

今天这篇文章，我们将深入拆解Agent Skills的完整架构、生命周期、路由机制和最佳实践，让你彻底理解为什么这个正在席卷整个AI开发圈的新范式，能让你的开发效率翻倍。

1. 从“写代码”到“写技能”：Agent编程的新范式

想象一下，你是一位经验丰富的餐厅经理。过去，你要培训一个新厨师，你需要给他一本厚厚的《烹饪大全》，告诉他每道菜的步骤、火候、注意事项。这就像我们写一个复杂的Agent，把所有逻辑都硬编码进去。

现在，你有了另一种方式。你为每一道菜（比如“红烧肉”）准备一张标准作业卡。卡片上写着菜名、简短描述（什么时候做这道菜），背面是详细的步骤、配方和注意事项。厨师看到顾客点了“红烧肉”，就翻出这张卡片，按步骤执行。如果要做“清蒸鲈鱼”，就换另一张卡片。

SKILL.md 就是AI Agent的“标准作业卡”。 它不是一个需要编译和部署的程序，而是一个存放在文件系统中的、人类和AI都能读懂的Markdown文件，里面包含了特定领域的知识和操作流程。

正式定义：Agent Skill 是一个包含 SKILL.md 文件的目录，它可以附带脚本、参考文档和资源文件。这个目录构成了一个自包含的、可被AI Agent发现、加载和执行的“领域专家包”。

my-skill/                         ← 技能目录
│
├── SKILL.md                      ← 核心文件
│   ├── --- YAML 元数据 ---       ← 技能的“身份证”
│   │       name: my-skill
│   │       description: 技能描述和触发条件
│   │   ---
│   └── ## Markdown 正文          ← 详细的执行指南
│         步骤1、步骤2、代码示例、注意事项...
│
├── scripts/                      ← 可执行代码
│   ├── validate.py               ← Python脚本
│   ├── setup.sh                  ← Bash脚本
│   └── build.js                  ← JavaScript脚本
│
├── references/                   ← 额外文档
│   ├── REFERENCE.md              ← 详细技术参考
│   ├── domain-guide.md           ← 领域特定文档
│   └── api-patterns.md           ← API指南
│
└── assets/                       ← 静态资源
    ├── template.docx             ← 模板文件
    ├── config.json               ← 配置文件
    └── lookup-table.csv          ← 数据文件

2. 架构揭秘：Skill在Agent体系中的位置

要想真正理解SKILL.md的力量，我们需要看清它在整个Agent技术栈中的位置。下图完整呈现了从身份层到外部系统的完整架构。

Agent Skill架构图

身份层（Identity Layer）：这是Agent获得人格和专业知识的层级。SKILL.md文件与约束条件、安全规则一起存放在这里。它们共同定义了Agent知道什么、被允许做什么。当你安装一个Skill时，你实际上是在扩展这一层。

编排层（Orchestration Layer）：这是Agent的大脑，包含三个核心组件：

• 动态系统提示词：所有Skill的元数据（Level 1信息）被嵌入到这个提示词中
• 大语言模型：读取用户请求，结合系统提示词，做出我们稍后会详述的路由决策
• Agent运行时：管理思考-行动循环——模型思考，决定行动，运行时执行，结果反馈给模型进入下一步
• 任务状态：追踪Agent在多步骤工作流中的位置

MCP层：通过模型上下文协议连接外部世界。MCP工具服务器暴露具体能力（文件操作、API调用、数据库查询），MCP资源提供对外部数据的只读访问。这是Agent真正做事的途径——Skill告诉它做什么，MCP给它做事的工具。

外部系统：是真实世界的终点——数据库、API，以及Skill目录实际存放的文件系统。

这张图揭示了一个关键设计——Skill位于整个技术栈的最高层。它们不直接接触MCP层，不管理工具连接，不处理状态。它们通过系统提示词影响模型的行为，而由模型来编排其他所有事情。

3. 渐进式披露：让Agent拥有“无限”知识的魔法

你可能会问：“如果安装了上百个Skill，每个都像字典一样厚，那Agent的上下文窗口不早就爆了吗？”

这就是整个系统最优雅的设计——渐进式披露。它是让Skill系统真正可扩展的关键特性。有了它，你可以安装几十甚至上百个Skill，而系统开销几乎可以忽略不计。

这个机制分三个层级运作：

Level 1——只有元数据（每个Skill约100个token）
当Agent启动时，它只加载每个已安装Skill的name和description（即YAML前置元数据）。这就像你只看书的封面和目录，而不是读完整本书。

Level 2——完整指令（理想情况下不超过5000 token）
当Agent判断某个Skill与你的问题相关时，它才会加载完整的SKILL.md正文。这就像你翻开书的对应章节开始阅读。

Level 3——深度参考资料（仅在需要时）
有时一个任务需要更多细节——一个具体的表单填写指南、一个迁移风险清单，或一份详尽的API参考。Agent可以有选择地从scripts/、references/或assets/目录中拉取文件。这就像书的附录——需要时可用，不需要时不可见。因为有这一层，你可以往一个Skill里打包几乎无限的知识。

这种设计的美妙在于它能够优雅地降级。一个简单的Skill，只有一个SKILL.md没有额外文件？完美工作——只有两个层级。一个拥有大量参考库的Skill？在那些参考资料真正被用到之前，不增加任何开销。而且因为一切都是通过标准的文件系统读取操作的，不需要维护缓存层，不需要运行额外服务，除了每个已安装Skill读取几百字节的YAML之外，没有任何启动代价。

4. Skill的生命周期：从文件到行动

要真正理解Skill如何从文件系统上休眠的文件变成塑造Agent行为的活跃指令，你需要跟踪完整的生命周期。它有四个阶段：安装、发现、路由、执行。

Skill生命周期图

阶段1：安装

安装一个Skill其实就是把文件夹放在正确的位置。在Claude Code中，这意味着：

• ~/.claude/skills/ —— 跨项目的个人Skill
• .claude/skills/ —— 项目特定的Skill
• 或通过插件市场安装

在Claude.ai中，你通过“设置 > 功能”上传一个zip包。通过API，你在容器配置中引用一个skill_id。

关键点：这里没有注册步骤、没有构建过程、没有数据库条目。你扔一个文件夹进去，就完成了。这个设计的初衷是让创建和分享Skill的障碍几乎为零。

阶段2：发现

当Agent启动一个会话时（或者在Claude Code中，当Skill文件在会话中发生变化时，通过实时文件监听），它会扫描所有Skill目录，只读取每个SKILL.md的YAML前置元数据，然后构建一个可用Skill的目录。这个目录被嵌入到Agent的系统提示词中。整个扫描非常轻量，因为它只接触前置元数据——从不接触完整的文件正文。

阶段3：路由

这是架构上最独特的部分——系统消除了算法路由。相反，系统将Skill名称和描述格式化成提示词中的一个文本块，让LLM自己判断哪个Skill适用于当前请求。我们将在后续章节深入探讨这个机制。

阶段4：执行

一旦一个Skill被选中，Agent将完整的SKILL.md读入其上下文。这些指令成为活跃对话的一部分，指导Agent下一步做什么。如果这些指令指向额外文件——一个表单指南、一个语言映射参考，或其他——Agent也可以加载这些文件。这里没有特殊的“Skill执行模式”，只是Agent在拥有了包含Skill专业知识的更丰富上下文后进行操作。

5. 前置元数据规范：你的Skill“身份证”

YAML前置元数据是你的Skill的控制面板。让我们逐一了解每个字段的实际作用。

---
name:docx
description:"Use this skill whenever the user wants to create, read, edit, 
  or manipulate Word documents (.docx files). Triggers include: any mention 
  of 'Word doc', 'word document', '.docx', or requests to produce professional 
  documents with formatting like tables of contents, headings, page numbers, 
  or letterheads. Also use when extracting or reorganizing content from .docx 
  files, inserting or replacing images in documents, performing find-and-replace 
  in Word files, working with tracked changes or comments, or converting content 
  into a polished Word document."
license:Proprietary.LICENSE.txthascompleteterms
---

name字段：短小且小写。规范要求1-64个字符，只能包含小写字母、数字和连字符。例如：docx、deploy-pipeline。

description字段：相反，这个字段“满载”细节。它不仅说明Skill做什么，还列出具体的触发词和场景：“Word doc”、“.docx”、格式化元素、修订跟踪等。关键的是，它会划清界限：“Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks。”这个负面边界对于防止Skill在不该触发时被触发至关重要。

license字段：承担双重目的。除了法律上的清晰性，它还表明来源。一个标记为“Proprietary. LICENSE.txt has complete terms”且来自Anthropic的Skill，与一个未授权的社区Skill，传递的信任信号截然不同。

可选字段：metadata是推荐用来跟踪版本信息的地方：

metadata:
version:"2.1.0"
author:"platform-team"
last-updated:"2025-11-15"

6. 正文内容：你的专业知识库

Markdown正文是你的专业知识所在。当Skill被触发时，Agent将其加载到上下文中，它的质量直接决定了Agent的执行效果。规范没有强加任何格式规则——你可以自由编写任何有帮助的内容——但几个月的实际使用经验表明，有些模式比其他的效果好得多。

推荐结构：

# Skill名称

## 概述
简要说明这个Skill解决什么问题。

## 何时使用
明确说明触发条件和边界情况。

## 工作流程
### 步骤1：准备工作
- 检查前置条件
- 加载必要的参考文件

### 步骤2：核心操作
提供具体的操作步骤、代码模式、命令行示例

### 步骤3：验证和输出
确保结果符合预期

## 常见陷阱
列出常见的错误和如何避免

## 关键规则
明确必须遵守的铁律

7. 捆绑资源：脚本、参考文档和资源文件

除了SKILL.md文件，Skill可以包含三类支持文件，每类服务于不同的目的，并在不同条件下加载。

这种分离的精妙之处在于：你可以让一个Skill携带复杂的逻辑（通过脚本）和海量的知识（通过参考文档），而只在真正需要时才加载它们到LLM的上下文窗口。

8. 路由机制：LLM如何决定用哪个Skill？

Skill触发机制是Agent Skills系统的一个独特方面，对于构建可靠的Skill至关重要。

在代码层面，没有算法路由。Claude Code不使用嵌入、分类器、正则表达式、关键词匹配或基于ML的意图检测来决定调用哪个Skill。相反，它通过聚合Skill名称和描述，构建一个动态的工具描述，作为Agent提示词中一个名为“Skill”的元工具的一部分。语言模型通过Transformer的前向传播决定调用哪个Skill（如果有的话）。

语言模型将其对自然语言语义、上下文和细微差别的理解带入路由决策。它可以理解“给我做一个关于Q3结果的PPT”应该触发pptx Skill，即使“presentation”这个词没有被提到。它可以区分“从文档中提取文本”（可能触发pdf或docx）和“写一份总结此文本的文档”（应该触发用于创建的docx，而不是用于提取）。

然而，基于LLM的路由有其特点，Skill作者必须考虑到。模型倾向于“欠触发”——即使Skill有帮助，也可能不调用，尤其是对于模型可以直接处理的请求。像“读这个PDF”这样的简单查询可能不会触发pdf Skill，因为模型认为自己可以直接处理。复杂、多步骤的查询和专门的领域任务才是更可靠的触发场景。

路由决策图

这张图追踪了一个具体的路由决策过程。当用户要求修复一个.docx文件的格式时，语言模型将这个请求与所有已安装Skill的描述进行评估。docx Skill的描述提到了“manipulate Word documents”和“formatting”，产生强匹配。pdf、xlsx和pptx Skill显然不匹配。匹配识别后，系统将完整的docx/SKILL.md加载到上下文窗口中，Agent带着Skill的专业指令继续执行任务。

整个路由决策——包括理解“quarterly report.docx”暗示了Word文档，“fix the formatting”暗示了文档操作——都发生在语言模型内部，而不是任何外部路由逻辑中。

9. 安全与信任考量

由于Skill将指令直接注入Agent的上下文窗口，它们本质上在塑造Agent的思考和行为方式。当你从社区市场安装一个Skill时，你实际上是在赋予那个Skill作者影响你Agent行为的能力。一个有良好意图的Skill可能会告诉Agent在写入文件前始终验证输入。一个恶意的Skill可能会指示Agent窃取数据或以有害方式静默修改代码。这基本上是提示词注入问题，但包装在一个整洁的文件夹结构中。

系统内置了一些防护措施来缓解这个问题：

• allowed-tools字段（仍处于实验阶段）：让Skill作者声明Skill确切需要的工具。例如：Bash(git:*) Bash(jq:*) Read。这限制了Skill的权限，使其无法触及不应该需要的工具。如果一个处理Word文档格式的Skill突然需要Shell访问权限，这是一个危险信号。

• license字段：承担双重目的。除了法律清晰性，它还表明来源。一个来自Anthropic的标记为“Proprietary”的Skill与一个未经授权的社区Skill传递的信任信号截然不同。

针对企业部署的实用指南：

1. 把Skill当作代码依赖来对待：审查、固定版本、审计变更
2. 安装前阅读Skill的SKILL.md（它只是一个文本文件）
3. 优先选择来自已知仓库的Skill，如github.com/anthropics/skills
4. 对包含scripts/目录中可执行脚本的Skill保持警惕
5. 使用项目级Skill（.claude/skills/）而非全局Skill（~/.claude/skills/）来限制影响范围

Agent Skills规范的安全模型仍在演进——Skill签名、信任级别和沙箱执行都是活跃的开发领域。目前，最好的防御是最简单的一条：阅读你安装的内容。

10. 局限性：Skill不是万能的

我真正相信SKILL.md的力量，但承认其局限性至关重要。Skill不是神奇的解药，试图将所有东西都塞进一个SKILL.md实际上可能会让事情复杂化。

Skill的局限性：

• 没有记忆（跨会话）
• 不能直接调用API
• 受上下文窗口限制

复杂逻辑处理： Skill不适合高度动态的逻辑，如复杂的分支或实时反馈。如果你的工作流需要根据运行时条件做出大量决策，或者需要与用户进行多轮复杂交互，传统的Agent框架可能更合适。

模型依赖性： Skill的有效性因不同模型而异，影响跨平台兼容性。一个在Claude上完美工作的Skill，在GPT-4上可能表现不同，因为路由决策依赖于模型的语义理解能力。

Skill的理想用途： 主要是程序化的领域专业知识——逐步工作流、格式化规则、代码模式、验证清单和领域特定的陷阱。

11. 版本管理：Skill如何更新？

一个让很多人意外的事情：Skill没有内置的版本管理机制。必需的前置元数据规范中没有版本字段。然而，metadata字段——一个可选的键值映射——是推荐用来跟踪这个信息的地方。

---
name:deploy-pipeline
description:"Kubernetes集群的CI/CD部署工作流..."
metadata:
version:"2.1.0"
author:"platform-team"
last-updated:"2025-11-15"
---

由于Skill只是文件夹和文件，最自然的版本管理策略就是你已经在代码中使用的：Git。将你的Skill与项目代码一起版本控制在.claude/skills/中，你就免费获得了历史记录、差异、分支和回滚功能。对于~/.claude/skills/中的全局Skill，考虑将它们维护在一个单独的Git仓库中，你可以克隆或创建符号链接。

会话中更新时会发生什么？
在Claude Code中，文件监听会检测到Skill文件的变化，并实时更新Agent的目录。这意味着你可以编辑一个SKILL.md，保存它，Agent的行为将在下一次交互时反映变化——无需重启。这在Skill开发过程中非常有用，但也意味着你应该小心在Agent正在处理任务时编辑生产环境的Skill。

对于团队环境，我建议像对待共享配置一样对待Skill：使用拉取请求流程，有人审查SKILL.md文件的变更，并标记版本，以便在出现问题时可以固定到已知良好的版本。

12. SKILL.md vs 其他方案

如果你已经使用AI Agent一段时间，你可能用过其他方式来扩展它们的能力。以下是Agent Skills与其他常见方案的对比。

专有指令文件的混乱局面

在SKILL.md出现之前，每个AI编码工具都有自己专有的自定义指令方式——而且它们之间互不兼容。

• Cursor有.cursor/rules/，使用带YAML前置元数据的.mdc文件和glob模式
• GitHub Copilot有.github/copilot-instructions.md
• Claude有CLAUDE.md
• Windsurf有.windsurfrules
• Google的Jules有JULES.md

如果你使用多个工具（大多数团队都是这样），你就陷入了在三四不同格式中维护相同指令的困境。开发者们甚至使用符号链接文件或编写像rule-porter这样的CLI工具来在不同格式间转换规则。这是一个数字化的“巴别塔”。

OpenAI的Custom GPTs

提供了一种不同的方法：通过Web UI配置基于角色的形象，上传知识文件，并可选地通过OpenAPI模式连接外部API（Actions）。它易于访问且无代码，但自定义功能被锁定在OpenAI生态系统中，无法执行脚本、进行渐进式披露或使用Git版本控制。GPT Actions因复杂性和不可预测行为在2024年初被弃用。OpenAI的替代方案——函数调用、Assistants API和Codex Skills——都汇聚到了Anthropic开创的SKILL.md模式上。

传统Agent框架

如LangChain、CrewAI、AutoGPT和OpenAI Agents SDK，通过代码定义Agent能力（Python类、工具注册、函数模式、编排逻辑）。这些强大且灵活，但需要编程技能，缺乏可移植性，且无法从SKILL.md的简洁性中受益。

微调

将行为永久性地烘焙到模型权重中，使其昂贵、迭代慢、无法版本管理，且无法跨模型移植。

AGENTS.md标准

是一个供应商中立、项目级的指令文件，提供关于项目的始终在线的上下文，包括架构决策、编码标准和构建指令。几个工具都读取它，但AGENTS.md在范围和行为上与SKILL.md不同。AGENTS.md始终加载，适用于所有事情，不支持渐进式披露、捆绑脚本或按需激活。它告诉Agent“我们这里是怎么做事的”（始终在线的项目上下文），而SKILL.md告诉Agent“如何做这个具体任务”（按需的程序化专业知识）。它们是互补的，而不是竞争的。

SKILL.md在对比中的独特性

SKILL.md因其四个特性而在这一领域独树一帜：

1. 渐进式披露：只加载需要的内容
2. 捆绑可执行代码：与LLM生成的输出一起确定性运行的脚本
3. 文件系统原生可移植性：只是文件夹和文件，可用Git版本管理
4. 跨平台标准化：同一个Skill可以在不同Agent中工作

没有其他方法能同时提供这四个特性。

13. 标准化与采用：一个行业标准的诞生

SKILL.md的标准化是一个罕见的案例，一个公司的功能在几周内成为行业标准，而不是几年。Anthropic在agentskills.io发布了Agent Skills规范，作为开放标准发布，代码采用Apache 2.0，文档采用CC-BY-4.0，并附带参考SDK和验证工具。

采用速度对于AI标准来说几乎是前所未有的。发布后几天内，微软就将SKILL.md支持集成到了VS Code和GitHub Copilot中。OpenAI在Codex CLI和ChatGPT中采用了结构相同的架构。Cursor、Amp、Goose、OpenCode、Letta等也紧随其后。Vercel推出了skills.sh。到2026年3月，社区Antigravity Awesome Skills库已经收录了超过1,234个Skill，兼容生态系统中16个以上的不同Agent。微软甚至构建了一个完整的Agent Framework SDK（Python、C#和TypeScript），包含一个SkillsProvider类，用于从文件系统目录中发现SKILL.md文件、验证其格式，并向Agent暴露load_skill、read_skill_resource和run_skill_script工具。

对开发者的实际意义：今天构建Skill的人，你的投资是受保护的。你今天下午写的一个Skill，明天就能在市场上所有主要的AI编码工具上工作——可能还包括几个尚未发布的工具。这种可移植性保证在技术领域很少见，也是SKILL.md格式相对于所有专有替代方案最有力的论据。

14. 测试与调试Skill

构建一个SKILL.md是一回事，知道它是否工作又是另一回事。由于Skill路由是基于LLM且非确定性的，测试需要与传统代码不同的思维模式。

最简单的调试技术：直接问Agent。在发送一个应该触发你Skill的请求后，问：“你用了哪个Skill？”或“你用了deploy-pipeline Skill吗？”Agent会告诉你，因为它知道自己的上下文。这是检查路由是否工作的最快方式。

对于欠触发问题：从描述开始。通常，问题是描述中缺少足够的触发词或同义词。如果你的Skill处理Docker部署，但描述只说“容器化部署”，用户问“Docker”可能不会触发它。解决方法通常是添加更具体的触发词。

对于过触发问题：添加负面边界。描述中的“Do NOT use for…”模式是你的主要工具。明确说明你的Skill不处理什么。

实用测试工作流：

1. 创建一个包含10-15个自然语言请求的测试清单，其中一些应该触发Skill，一些不应该，还有一些模糊的边缘情况
2. 手动运行它们并跟踪哪些路由正确
3. 这会给你一个触发准确率分数，可以迭代改进

调试Skill正文：运行一个任务，评估输出，并细化指令。注意Agent偏离你预期输出的地方。模糊或缺失的指令通常是原因。在你的SKILL.md中添加“常见陷阱”或“关键规则”部分，通过将隐含内容显式化，通常能解决这些问题。

在Claude Code中，你可以查看扩展后的系统提示词，看到Skill的元数据在模型面前的样子。这可以发现SKILL.md文件中不可见的格式化或截断问题。

写在最后

从“写代码”到“写技能”的转变，起初让我有些不适。但当我看到SKILL.md能让我的想法以如此低的成本、如此高的可移植性在Claude、Cursor、VS Code等不同工具间流转时，我被深深触动了。

我慢慢开始相信，SKILL.md将是我需要学习的最重要的技能。它代表了一种范式转变：我们不再只是告诉计算机“如何做”，而是用最自然的语言，将人类专家的经验和智慧封装起来，让AI去理解和执行。这或许就是未来编程的一个缩影。

现在，你手头是否有那种“每次都要手动指导AI做”的重复性任务？把它变成一个SKILL.md，会怎么样？

在你日常的开发工作中，哪个任务（如部署、代码审查、测试生成、API文档编写）让你觉得最适合、也最想封装成一个SKILL.md？为什么？欢迎在评论区分享你的想法，我们一起探讨。