Agent Skills 完全指南：2026 年 AI 协作的「员工手册」是怎么炼成的

本文由 辛梓煜@词元二号站（www.ciyuanerhao.com）撰写，转载请注明出处。

快速摘要

Agent Skill（智能体技能）是 2025 年底由 Anthropic 推出、2026 年上半年被几乎所有主流 AI 编程工具全面跟进的一项核心能力。它的本质是一套给 AI 看的「标准操作手册」——把重复性高、有明确规范的工作流程封装成 Markdown 文件，让 AI 按需加载、自动执行。Skill 最革命性的设计叫「渐进式披露」：元数据始终可见（约 100 token/个），核心指令只在任务匹配时加载，脚本和参考资料按需读取——这意味着你可以拥有几十个 Skill，但上下文窗口始终清爽。Skill 不是 Rule 的替代品，也不是 MCP（Model Context Protocol，模型上下文协议）的竞争对手，它填补的是「AI 知道用什么工具，但不知道怎么组合使用」的能力空白。这篇文章会把 Skill 的概念、原理、写法、存放策略、生态现状和避坑经验全部拆开揉碎讲清楚。

如果你每天用 AI 编程工具超过两小时，花 30 分钟写好一个 Skill，一个月后你的效率提升会远超想象——因为你只需要写好一次，它就能替你省下无数次重复解释的时间。想看完整拆解，往下翻。

一、从「每次教 AI」的抓狂说起

我猜你大概率经历过下面这种场景。

打开 Cursor 或者 Claude Code，准备让 AI 帮你写一个新功能。对话窗口一片空白，你先敲了一大段：「我们这个项目用 React 18，状态管理是 Zustand，CSS 框架是 Tailwind，组件命名用 PascalCase，文件结构按功能模块拆分，API 请求统一走 services 层封装，错误处理要用统一的 ErrorBoundary……」

打完这段，三分钟过去了。AI 终于理解了你的项目环境，开始干活。

第二天你打开一个新对话，想继续昨天的任务。然后你发现——对不起，AI 又变成了一张白纸。你昨天花了三分钟「培训」它的那些规矩，全部清零。你又得从头再来一遍。

这种感觉，就像你雇了一个记忆力只有 7 秒的助手。它聪明、能干活，但每次交接任务你都得把整个项目的背景重新交代一次。你说烦不烦？

这个痛点不是你的问题，是大模型的一个「先天性缺陷」：大模型没有记忆。每次开启新对话，对 AI 来说都是全新的一次交互。它不会记住你上一轮说过什么、约定过什么规范、偏好什么风格。这是 Transformer 架构在推理阶段的无状态特性决定的，不是什么 bug，而是底层设计使然。

业界为解决这个问题，经历了三代方案的演进。

第一代是 Prompt 模板。把常用的提示词存成一个 txt 文件，每次用的时候复制粘贴。这个方法人人都用过，效率极低——你得手动找、手动粘，而且一大段 Prompt 塞进上下文，Token 消耗惊人。

第二代是 Rule（规则文件）。在项目根目录放一个 .cursorrules 或 CLAUDE.md，AI 打开项目时自动加载。这一步解决了「每次手动粘贴」的问题，但带来了新麻烦：Rule 是全量加载的。不管你这次对话是写前端组件还是改数据库配置，Rule 文件里所有的规范都会一股脑塞进上下文。一个项目配三五个 Rule 还好，但如果你的 Rule 细致到覆盖了代码风格、测试规范、文档格式、部署流程、API 设计……十几个 Rule 堆在一起，上下文窗口很快就撑满了。

第三代，就是本文要聊的主角——Agent Skill。2025 年 10 月，Anthropic 在 Claude Code 中首次推出这个功能。到 2026 年初，Cursor、GitHub Copilot、TRAE、CodeBuddy、Windsurf 等主流工具全部跟进。短短半年不到，从一个实验性特性变成了行业标配。Gartner 预测，到 2026 年底，40% 的企业应用将集成特定任务的 AI Agent，而 Skill 正是支撑这套 Agent 体系的核心能力模块。

Skill 解决了一个关键问题：让 AI 自己判断什么时候该用什么规则，而不是每次都把全部规则塞给它。你只需要写好 Skill 文件，放在对应目录下，AI 会根据你的任务描述自动匹配、按需加载——平时不占内存，需要时才激活。这个机制让「几十个专业规范并存」从不可能变成了可能。

听起来挺简单对吧？但这里面藏着一套非常精巧的设计。接下来我们一步步拆开看。

——辛梓煜@词元二号站

二、Agent Skill 到底是什么

一句话概括：Agent Skill 是给 AI 看的「员工手册」。

我知道这个比喻已经被用得有点泛滥了，但它确实是最准确的。想象你开了一家餐厅，雇了一个新厨师。这厨师科班出身，基础功扎实，但对你们店的流程一无所知。你要是不给他任何指导，他做的宫保鸡丁可能今天偏甜、明天偏辣——全凭手感。

但如果你给了他一本标准操作手册，上面写着：「第一步，鸡腿肉切 2 厘米丁，料酒腌 10 分钟；第二步，花生米提前炸好备用；第三步，热锅凉油，花椒辣椒先下，肉丁滑至变白捞出；第四步，调碗汁——酱油两勺、醋一勺半、糖一勺、淀粉半勺……」——那不管这个厨师今天是心情好还是心情差，做出来的菜都一样。

Skill 就是这本手册。它告诉 AI：在什么情况下、按照什么流程、达到什么标准。

技术层面的定义

从技术角度看，一个 Skill 就是一个包含 SKILL.md 文件的文件夹。这个文件夹里封装了完成特定任务所需的全部「知识」——包括指令（Instructions）、参考文档（References）、可执行脚本（Scripts）和模板资源（Assets）。

AI 在收到用户请求后，会先扫描所有已安装 Skill 的「元数据」（名称 + 描述），判断当前任务是否与某个 Skill 匹配。匹配上了，就加载该 Skill 的完整指令；匹配不上，就忽略。整个过程对用户是透明的——你不需要手动指定「请使用 XXX Skill」，AI 自己会判断。

一个典型的 Skill 文件夹结构长这样：

my-skill/
├── SKILL.md           # 核心文件：元数据 + 操作指令（必需）
├── references/         # 参考文档：规范、手册、知识库（可选）
│   ├── style-guide.md
│   └── api-docs.md
├── scripts/            # 可执行脚本：Python/Bash（可选）
│   └── validate.py
└── assets/             # 模板与静态资源（可选）
    └── report-template.md

这里面 SKILL.md 是唯一的必需文件。只要写了它，一个 Skill 就能跑起来。其他三个目录都是可选的增强模块，后面会细讲。

从 2025 到 2026：半年走完五年的路

Agent Skill 的发展速度，用「爆发」来形容一点都不夸张。

• 2025 年 10 月：Anthropic 在 Claude Code 中正式发布 Agent Skill 功能。
• 2025 年 12 月：Anthropic 将 Skill 规范作为开放标准发布在 agentskills.io，任何工具都可以接入。
• 2026 年 1 月 - 3 月：Cursor、Windsurf、GitHub Copilot、TRAE、CodeBuddy、Roo Code 等主流 AI 编程工具相继宣布支持 Agent Skill 标准。
• 2026 年 Q2：Skill 生态爆发——社区出现多个 Skill 市场，如 Agensi、SkillHub（7000+ 个经 AI 评估的 Skill）、SkillsMP 等。SkillsBench 的分析显示，公开可获取的 Skill 数量已达 47150 个。

Anthropic 这一步棋走得非常聪明：他们没有把 Skill 做成 Claude 的私有特性，而是直接开源了标准。结果就是，整个行业都跟着这个标准走，Skill 从一个「Claude 独家功能」变成了「AI 编程工具的通识能力」。对用户来说，这意味着你写好的 Skill 可以在多个工具间复用——在 Claude Code 里用的代码审查 Skill，拿到 Cursor 里照样跑。

——辛梓煜@词元二号站

三、渐进式披露：Skill 能省下 90% Token 的秘密

如果前面两章你只读个大概，那这一章请认真看完。渐进式披露（Progressive Disclosure）是 Agent Skill 最核心的设计哲学，也是它能碾压 Rule 模式的根本原因。

要理解渐进式披露，先得理解一个前提：上下文窗口是一种公共资源，而且极其稀缺。

主流大模型虽然上下文窗口越来越大——Claude 支持 200K，GPT-4 支持 128K——但这不意味着你可以无脑往里塞东西。上下文越多，模型推理越慢、成本越高、回复质量越可能下降（业内叫「上下文退化」）。更关键的是，上下文里塞的东西越多，留给用户对话的「有效空间」就越少。你塞了一万字的 Rule，用户就只能问一万字的问题。

Skill 解决这个问题的思路非常优雅，叫做「三层加载」。

三层架构，逐级披露

graph TD
    A[用户发送请求] --> B[AI 扫描所有 Skill 元数据]
    B --> C{是否匹配某个 Skill?}
    C -->|否| D[直接回答，不加载任何 Skill]
    C -->|是| E[加载该 Skill 的 SKILL.md 完整内容]
    E --> F{指令中是否引用了 references?}
    F -->|是| G[按需读取参考文档]
    F -->|否| H[执行指令]
    G --> H
    H --> I{指令中是否引用了 scripts?}
    I -->|是| J[执行脚本，返回结果]
    I -->|否| K[生成最终回答]
    J --> K

这张图展示的就是渐进式披露的完整流程。下面逐层拆解。

第一层：元数据（始终加载）

每个 Skill 的 SKILL.md 文件都以 YAML Frontmatter 开头，长这样：

---
name: code-review
description: Review code for security vulnerabilities, performance issues, and code style. Use when user asks 'review this code', 'check my code', or 'code audit'.
---

当 AI 启动时，它会扫描所有已安装 Skill 文件夹，只读取每个 SKILL.md 的 Frontmatter 部分。这部分信息极短——实测每个 Skill 的元数据大约只消耗 100 个 token。

这意味着什么？意味着哪怕你装了 50 个 Skill，初始的上下文消耗也只有约 5000 token。对于 200K 的上下文窗口来说，这连 3% 都不到。

元数据层的作用就像书架上的书脊——你扫一眼书名和副标题就知道这本书讲什么，不需要翻开看。

第二层：核心指令（匹配后加载）

当 AI 判断用户当前任务与某个 Skill 的描述匹配时，它才会「翻开书」——把该 Skill 的 SKILL.md 完整内容加载进上下文。

这一层包含的是实际的操作指令：分步流程、输出格式、决策规则、注意事项等。根据最佳实践，SKILL.md 内容建议控制在 5000 token 以内，保证在按需加载时不会过度占用上下文。

关键点来了：不匹配的 Skill，这一层的内容完全不会加载。这就是 Skill 和 Rule 的本质区别——Rule 的「全量加载」意味着不管今天的任务是什么，所有规则都堆在上下文里；而 Skill 的「按需加载」意味着今天写前端，只有前端相关的 Skill 会被激活，后端、数据库、部署相关的 Skill 全部静默。

第三层：配套资源（深度按需加载）

这一层是最精妙的。Skill 文件夹里可以放参考文档（references）、脚本（scripts）和模板（assets），但它们不会因为 Skill 被触发就自动全部加载。

• References（参考文档）：只有当 Skill 指令中明确说「读取 references/xxx.md」时，AI 才会去读那份文档。
• Scripts（脚本）：更特殊——脚本不是被「读」的，而是被「跑」的。脚本代码本身不进入上下文，只有执行结果会返回给 AI。这意味着零上下文成本 + 确定性结果。
• Assets（模板）：如报告骨架、文件模板，按需读取填充。

对比一下这三层加载的特性：

一个真实的数据对比

我拿自己的项目实际测过一次。假设你有一个中型项目，日常需要的规范包括：代码风格、测试规范、文档模板、API 设计规范、Git 提交规范、安全审查清单、性能优化指南——共 7 个模块，每个模块约 3000 字的规范文本。

如果全部写成 Rule：每次对话，这 7 份规范约 21000 字全部塞进上下文。意味着每次对话一开始，你的上下文就有五分之一被占满。

如果写成 7 个 Skill：初始加载只有 7 个 Skill 的元数据，约 700 token。写前端代码时，只有前端相关的那 1-2 个 Skill 会被触发，上下文额外增加约 3000-6000 token 的指令。其他 5-6 个 Skill 完全静默。

算下来，Skill 方案的上下文节省率在 65%-90% 之间。而且 Skill 数量越多，这个优势越明显——因为 Rule 模式下 N 个 Rule 全部加载，而 Skill 模式下每次只加载相关的 1-3 个。

这也是为什么 2026 年几乎所有主流 AI 编程工具都选择了 Skill 模式：Rule 模式在「少而精」的时候还行，一旦规范体系变复杂，就会遇到上下文瓶颈。Skill 的渐进式披露，本质上是一种把隐性知识结构化、让上下文利用效率最大化的设计。

不要把 references 和 scripts 搞混

这里补充一个容易踩的坑。references 目录下的文件和 scripts 目录下的脚本，虽然都在 Skill 文件夹里，但它们的加载机制完全不同：

• references 目录：文件是「读」的。AI 通过文件读取工具打开 references/style-guide.md，文件内容进入上下文窗口，消耗 Token。适合放编码规范、术语表、流程说明这类「AI 需要记住才能执行」的知识。
• scripts 目录：脚本是「跑」的。AI 通过 Shell 工具执行 scripts/validate.py，只有 stdout/stderr 返回给 AI。脚本代码本身不进上下文，不消耗 Token。适合放复杂计算、格式校验、数据转换这类「不需要 AI 理解过程、只需要结果」的逻辑。

一个判断标准：如果你写的内容需要 AI「理解并灵活运用」，放 references；如果内容是一段「输入→处理→输出」的确定性逻辑，放 scripts。举个例子——你要检查一个 TypeScript 文件的圈复杂度。圈复杂度的计算逻辑很固定，不需要 AI 理解，直接写一个 Python 脚本跑出结果就行。但「圈复杂度超过多少算有问题、不同项目类型的阈值怎么设」——这些判断标准需要 AI 灵活掌握，应该写在 references 里。

这种设计思路其实暗合了软件工程里「声明式 vs 命令式」的区别：references 是声明式的（描述「是什么」），scripts 是命令式的（定义「怎么做」）。把二者分开，Skill 的可维护性会好很多。

——辛梓煜@词元二号站

四、Skill vs Rule vs MCP vs Plugin：一张表彻底分清

每次我跟人聊 Skill，对方一定会问：「它跟 Rule 有什么区别？」「那跟 MCP 又是什么关系？」「Plugin 呢？」

这四个概念确实容易搞混，因为它们都「让 AI 更强大」，但发力点完全不同。我把对比拆成两张表——先看「是什么、用在哪儿」，再看「怎么跑、成本高不高」。

表一：定位与场景

表二：加载方式与成本

Rule：AI 的「性格设定」

Rule 是最早出现的一代方案。你在项目根目录放一个 .cursorrules 或 CLAUDE.md，里面写着「用 TypeScript 写所有代码」「组件命名用 PascalCase」「注释用中文」——AI 每次打开项目都会读这个文件，把里面的规则作为自己的「默认行为准则」。

Rule 适合那些「永远适用」的设定。比如你永远用 TypeScript，永远用 pnpm，永远在 src/components/ 下放组件——这些不需要 AI 判断「该不该用」，直接用 Rule 写死就好。

但 Rule 的致命问题是全量加载。一个 Rule 文件里写了 20 条规范，哪怕这次对话只涉及其中 1 条，剩下 19 条也在上下文里占着坑位。Rule 多了，上下文就炸了。

Skill：AI 的「操作手册」

Skill 补上了 Rule 最缺的能力：按需加载。Skill 的元数据始终可见，但核心指令只在匹配时加载。这意味着你可以有几十个 Skill，而上下文始终保持清爽。

Skill 还比 Rule 多了一样东西：可执行脚本。你的 Skill 文件夹里可以放一个 validate.py，AI 在执行任务时直接跑这个脚本——脚本代码不进上下文，只有结果回来。这是 Rule 完全做不到的。

简单总结：Rule 是贴在墙上的家规，人人得见；Skill 是书架上的工具书，需要时才取下来看。

MCP：AI 的「工具箱」

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 推出的另一个开放标准——但它解决的是完全不同的问题。

MCP 让 AI 能连接外部系统：查数据库、调 API、读文件系统、操作第三方服务。它定义了一套标准的「工具描述」格式，让 AI 知道「我有哪些工具可以用、每个工具的参数是什么」。MCP 是 AI 的「手」，让 AI 能触达外部世界。

Skill 和 MCP 不是竞争关系，而是配合关系。Skill 告诉 AI「怎么做」（流程），MCP 给 AI「用什么做」（工具）。一个完整的 AI Agent 工作流通常是：Skill 定义流程 → 流程中需要查数据时调用 MCP → MCP 连接外部系统返回结果 → Skill 继续执行下一步。

Plugin：AI 的「新器官」

Plugin 是四个概念里最「重」的。它不是一个 Markdown 文件，而是一个需要写代码的扩展程序——通常是 JavaScript 或 TypeScript。Plugin 可以改变编辑器界面（加侧边栏、加按钮）、创建自定义命令、调用编辑器的底层 API。

Plugin 的能力上限最高（因为你可以写任意代码），但门槛也最高（需要理解编辑器扩展 API，还要处理版本兼容）。对绝大多数日常需求来说，写一个 Markdown 文件就能搞定的 Skill，远比写一个 Plugin 划算。

一句话记住四个的区别

我常用的记忆口诀：Rule 是性格，Skill 是手艺，MCP 是工具箱，Plugin 是新器官。 选哪个，看你要解决什么问题——想让 AI 记住「你是什么风格」用 Rule，想让 AI「按流程干活」用 Skill，想让 AI「连接外部系统」用 MCP，想「改造编辑器本身」才用 Plugin。

实际使用中，这四个通常是组合出现的。一个典型的 AI 编程工作流可能是这样：Rule 定义了「始终用 TypeScript + Tailwind」的基调；当你说「帮我写一个登录表单」时，frontend-design Skill 被触发，按规定的流程生成组件代码；组件里需要调用后端 API 时，MCP 连接测试环境的数据库验证接口格式；而如果你觉得默认的编辑器界面不够顺手，才需要写 Plugin 来自定义。

对绝大多数日常使用场景来说，Rule + Skill 的组合已经能覆盖 90% 的需求，MCP 和 Plugin 属于进阶玩法。不用一上来就把四个全折腾一遍——先把 Skill 用熟，其他按需学习。

——辛梓煜@词元二号站

五、拆解一个 SKILL.md：从元数据到脚本

前面聊了很多概念，这章我们来点硬核的——把 SKILL.md 的文件结构拆开揉碎，每一部分讲清楚它干什么用、怎么写、有什么坑。

YAML Frontmatter：Skill 的「身份证」

每个 SKILL.md 文件都以一段 YAML Frontmatter 开头，用 --- 包裹。这是 AI 判断「要不要用这个 Skill」的唯一依据。长这样：

---
name: code-review
description: >
  Review code for security vulnerabilities, performance issues,
  and code style violations. Use when the user asks to 'review code',
  'audit this file', 'check for bugs', or 'code quality check'.
  Supports TypeScript, Python, and Go.
---

两个字段都是必填的。name 是 Skill 的唯一标识，建议用「动词-ing」格式，比如 analyzing-data、generating-report、reviewing-code。这种命名约定让 Skill 库在按字母排序时天然按功能分组。description 我们下一章专门讲，这里先跳过。

除了必填字段，YAML Frontmatter 还支持一些可选字段：

---
name: enterprise-code-review
description: Security-first code review for enterprise Java/TypeScript projects.
license: MIT
compatibility: claude-code, cursor, codebuddy
tags: [secur