Agent Skill 是一个包含指令的文件夹，还可以选择性地包含脚本和参考文件，AI Agent 只会在任务真正需要时自行加载它。

在这篇博客中，我们将学习 Agent Skills。我们还会了解为什么需要它们，一个 Skill 内部包含什么，描述如何让 Agent 自行选择正确的 Skill，渐进式披露如何保持上下文窗口的清爽，Agent Skills 与 MCP 的区别，以及我们如何创建自己的 Skill。

我们将涵盖以下内容：

  • Agent Skills 出现之前的问题
  • 什么是 Agent Skills？
  • 一个 Skill 内部包含什么？
  • 描述就是触发器
  • 渐进式披露，核心思想
  • 一个 Skill 可以携带真正的代码
  • Skill 存放的位置
  • 我们如何创建自己的 Skill？
  • Agent Skills 与 MCP
  • 一个真实的例子
  • Agent Skills 的重要性
  • 我们必须注意的事项
  • 总结

我是 Amit Shekhar，Outcome School 的创始人，我曾教导和指导过许多开发者，他们的努力为他们赢得了高薪的技术工作，帮助许多科技公司解决了他们独特的问题，并创建了许多被顶级公司使用的开源库。我热衷于通过开源、博客和视频分享知识。

我在 Outcome School 教授 AI 和机器学习。

让我们开始吧。

Agent Skills 出现之前的问题

在深入了解 Agent Skills 之前，我们必须理解它们所解决的问题。

AI Agent 是一种逐步采取行动来为我们完成任务的 AI。它可以读取文件、运行命令和使用工具。

现在，一个 Agent 总体上能力很强，但它不知道我们团队是如何做事的。它不知道我们公司的报告格式。它不知道我们团队发布软件所遵循的确切步骤。它不知道我们的品牌从不使用某个特定的词。

那么，我们该怎么做？我们每次都要把所有这些内容输入到聊天中。

我们肯定遇到过这种情况。周一我们解释同样的八个步骤。周三我们又解释一遍。下一周我们再向一位同事解释一次。这些知识存在于我们的脑海中，而我们一直在付出把它打出来的成本。

   Monday:     we type the 8 steps again
   Wednesday:  we type the 8 steps again
   Next week:  our teammate types the 8 steps again

在这里，我们可以看到浪费。知识是稳定的，但努力却在永远重复。

现在，我们可能会认为答案很简单。让我们把所有内容写进一个大的指令文件中，并让这个文件始终保持加载状态。

但是，问题来了。那样也行不通，我们必须理解为什么。

AI Agent 通过一个称为上下文窗口的有限空间来读取一切内容。可以把它想象成 Agent 的办公桌。桌面上一次只能放那么多页纸。我们持续加载的每一条指令都会永远占据桌面空间，即使它与当前任务毫无关系。加载二十个流程，Agent 在尝试执行第二十个时，却要读着十九个不相关的流程。

决定什么值得占用这个有限空间本身就是一门学问。我们有一篇关于 上下文工程 的详细博客，从头到尾涵盖了这一主题。

因此，我们需要一种方法，让 Agent 获得深度知识，而不必把所有知识都一直放在桌面上。

我们需要一个解决方案。于是，Agent Skills 应运而生。

什么是 Agent Skills？

Agent Skill 是一个包含指令的文件夹，还可以选择性地包含脚本和参考文件，AI Agent 只会在任务真正需要时自行加载它。

Agent Skills 由 Anthropic 于 2025 年 10 月推出，格式是开放的，任何人都可以编写，任何人都可以使用。

简单来说，Skill 就是一套书面指令，教会 Agent 如何出色地完成某一项特定工作。我们只需编写一次，每当这项工作出现时，Agent 就会自行调用它。

为了便于理解，让我们把这个术语拆解一下。

Agent Skills = Agent + Skills

Agent 是执行工作的 AI。Skill 是它学会的一项特定能力。因此，Agent Skills 就是我们交给 Agent 的那些特定能力。

想象一位新员工加入我们的团队。他们已经很聪明，也已经掌握了专业知识。但他们不了解我们的办公室。所以，我们不需要从零开始重新培训他们，而是把团队手册交给他们。手册里有独立的章节。一章讲如何报销费用，一章讲如何发布软件，一章讲如何撰写报告。

新员工不会每天早上都通读整本手册。他们只有在面对某项具体工作时，才会翻开对应的章节。

Skill 正是这样一个章节。而 Agent 足够聪明，能够自己打开正确的章节。

一个 Skill 内部包含什么？

现在，让我们打开一个 Skill，看看里面有什么。Skill 只是电脑上的一个文件夹，这意味着我们可以像对待其他任何文件夹一样阅读、编辑和分享它。

在那个文件夹里，有一个必需的文件，叫做

SKILL.md

。这个

.md

结尾表示它是一个 Markdown 文件，也就是一种带有轻量格式的纯文本文件。

Note:

它没有什么特别或神秘之处。我们可以用任何文本编辑器打开它。

一个

SKILL.md

文件包含两个部分。

第一部分位于最顶端，夹在两行短横线之间。这个顶部部分称为 frontmatter，它保存着描述该 Skill 的标签。其中两个重要的标签是

name

和

description

.

第二部分是正文，即 frontmatter 之下的所有内容。正文包含实际的指令，用平实的英文写成。

我们来看一个如下的小例子：

---
name: weekly-report
description: Creates the weekly team report in our company format. Use this whenever the user asks for a weekly report or a team update.
---

# Weekly report

Follow these steps.

First, collect all the tasks finished in the last seven days.
Then, group them under three headings: Shipped, In Progress, and Blocked.
After that, write one short line for each task. Never write more than one line.
Finally, put the total count at the top.

Never include internal ticket numbers in the final report.

在这里，我们可以在一个小文件中看到完整的思路。顶部部分告诉 Agent 这个 Skill 是什么以及何时使用它。正文则告诉 Agent 具体如何完成这项工作。两部分都是平实的英文，我们没有编写一行编程代码。

注意：

name

必须用小写字母书写，用连字符代替空格，例如

weekly-report

。这个

description

是平实的英文，我们必须保持简短，让人一口气就能读完。

一个 Skill 文件夹还可以在

SKILL.md

旁边存放其他文件，比如参考文档、模板或脚本。我们稍后会讲到这些。

描述就是触发器

现在，最重要的问题是：Agent 如何知道何时使用我们的 Skill？

答案就是

description

.

Agent 会读取每个可用 Skill 的

name

和

description

。然后，当我们提出请求时，它会把我们的请求与这些描述进行比较，并决定哪个 Skill 合适。

所以，

description

不是装饰。它就是触发器。模糊的描述意味着 Skill 一直闲置。清晰的描述意味着 Skill 会在正确的时刻被触发。

我们来比较两个描述。

   Weak:    "Report helper."
            The agent cannot tell when this applies. It stays unused.

   Strong:  "Creates the weekly team report in our company format.
             Use this whenever the user asks for a weekly report
             or a team update."
            The agent knows exactly what it does and when to use it.

在这里，我们可以清楚地看到区别。强描述说明了 Skill 做什么以及何时使用它。这正是 Agent 需要的两样东西。

注意： 我们写描述是给 Agent 读的，不是给人类欣赏的。

计划转型进入 AI 领域？

无论你今天在哪个技术领域工作，只要付出努力，你都可以转型到以下这些角色：

  • AI 工程师
  • 前沿部署工程师
  • AI Agent 工程师
  • Harness 工程师
  • 语音 AI 工程师
  • AI 架构师
  • LLM 工程师
  • LLM 推理工程师
  • 生成式 AI 工程师
  • MLOps 工程师
  • 机器学习工程师
  • 深度学习工程师

Outcome School 的 AI 与机器学习课程 将带你抵达那里。

渐进式披露，核心思想

现在，我们来到 Agent Skills 的核心。正是这一个理念让它们得以运作，所以我们慢慢来。

记住我们的问题。Agent 的桌面很小，我们无法把所有东西都放在上面。

Agent Skills 通过一种叫做渐进式披露的机制来解决这个问题。这个词听起来很重，但想法很简单。它意味着分阶段呈现信息，并且只呈现当前所需的内容。

它分为三个层级运作。

第 1 级。 一开始，Agent 只加载每个 Skill 的

name

和

description

。每个只有几行。所以即使有五十个 Skill，在桌面上也几乎不占空间。此时 Agent 只知道这个 Skill 存在，对它一无所知。

第 2 级。 我们提出请求。Agent 将我们的请求与描述进行匹配，并判断需要这个 Skill。只有这时它才会读取完整的正文

SKILL.md

。详细的指令恰好在变得有用时才到达。

第 3 级。 如果正文指向文件夹中的另一个文件，比如一份很长的参考文档，Agent 只有在确实需要时才会打开那个文件。

   Level 1  ->  name + description only          (always loaded, tiny)
   Level 2  ->  the full SKILL.md instructions   (loaded when it matches)
   Level 3  ->  extra files in the folder        (loaded only if needed)

让我们用一些真实的数字来说明，因为这些数字能很好地解释它为什么如此有效。

我们用来衡量桌面空间的单位叫做 token，大致相当于一个词的一部分。第 1 级对每个 Skill 只花费大约一百个 token。第 2 级的完整正文通常保持在五千个 token 以内，而且我们只为实际正在使用的那一个 Skill 支付这个成本。

现在，让我们比较这两个数字，因为这个对比非常惊人。五十个 Skill 在第 1 级总共花费大约五千个 token。这与一个 Skill 的正文相同。所以，知道五十个流程的存在，其成本不超过完整阅读其中一个。

在这里，我们可以看出为什么这很聪明。Agent 的表现就好像它深入了解五十个流程，而它的桌面却几乎空着。任何东西在被证明有价值之前都不会被加载。

这正是一本好的手册所做的事情。目录很短，总是摆在我们面前。章节很长，我们只在需要时才打开它。

给你的一个快速提示

无论你在哪个技术领域工作，都要熟悉这些主题：

  • LLM
  • RAG
  • MCP
  • Agent
  • 微调
  • 量化

我们把它们全部整合在一个视频中：

AI 工程详解：LLM、RAG、MCP、Agent、微调和量化

不必停止阅读——先收藏它，等有空时再看。未来的你会感谢现在的你。

现在，让我们回到主题。

一个 Skill 可以携带真正的代码

现在，让我们再了解一个让 Skill 强大的特性。

一个 Skill 文件夹可以存放一个脚本，也就是一个可以运行的小程序。当任务涉及精确、可重复的操作时，我们把脚本放进文件夹，指令会告诉 Agent 去运行它。

那么，为什么这一点如此重要？让我们理解其中的区别。

没有脚本时，Agent 每次都必须自己编写代码。它思考、编写，有时写得略有不同，而所有这些编写过程都会占满桌面。

有了脚本，Agent 只需运行一个现成的、经过测试的文件。每次的结果都相同，而且几乎不占用桌面空间。

   Without a script:  the agent writes the code again each time
                      (slower, and the result can vary)

   With a script:     the agent runs one tested file
                      (fast, and the result is the same every time)

在这里，我们可以看到一条简单的规则。如果任务需要判断力，我们就用平实的语言编写指令，让 Agent 去思考。如果任务需要精确性，我们就编写脚本，让 Agent 去运行。

Skill 存放的位置

现在，让我们看看这些文件夹存放在哪里。有两个常见位置，而它们的区别很重要。

个人技能。这些技能存放在我们自己的主文件夹中，位置类似

~/.claude/skills/

.

Note:

这个

~

符号只是主文件夹的一种简写方式。这些技能只属于我们自己，并且在我们参与的每个项目中都可用。适合我们个人的工作习惯。

项目技能。这些技能存放在项目本身内部，位置类似

.claude/skills/

。因为它们位于项目内部，所以会随项目一起移动。当队友把项目复制到自己的电脑上时，他们会自动获得所有技能，无需任何人告知。

   ~/.claude/skills/   ->  our personal Skills, in every project
   .claude/skills/     ->  the project's Skills, shared with the whole team

在这里，我们可以注意到项目技能的真正好处。我们团队的知识不再只存在于某个人的头脑中，而是开始存在于项目内部，每个人都能免费获得。

。这个

.claude

名称属于一个编码 Agent，它会在会话开始时读取此类文件夹。我们有一篇关于

How does Claude Code work?

的详细博客，解释了它如何读取我们的项目文件。

我们如何创建自己的 Skill？

现在，让我们自己创建一个。最棒的是，无需安装任何东西，也无需编写任何代码。

第 1 步：在我们的项目内，创建文件夹路径

.claude/skills/

.

第 2 步：在其中创建一个以我们的技能命名的文件夹，比如

weekly-report

.

第 3 步：在该文件夹内，创建一个名为

SKILL.md

.

第 4 步：在该文件的顶部，写入包含

name

和

description

.

第 5 步：在 frontmatter 下方，用平实的英语写出步骤，就像我们向新队友解释时那样。

整体效果如下所示：

   our-project/
     .claude/
       skills/
         weekly-report/
           SKILL.md

在这里，我们可以看到它实际上有多小。一个文件夹和一个文本文件，我们的技能就准备好了。

现在，这是撰写正文的最佳方式。我们必须想象自己是在为一位能干的新队友写作，这个人已经了解这个职业，但不了解我们的办公室。所以，我们跳过他们已经知道的一切，只写下我们特有的内容。这一个习惯就能产出好的技能。

要掌握 Agent 架构、Agent 中的工具使用以及 Agentic AI，我们可以在 Outcome School 的 AI 与机器学习课程 中从零开始构建一个 AI 编码 Agent。

Agent Skills 与 MCP

现在，下面这个问题出现了。还有一种叫做 MCP 的东西也能给 Agent 带来新能力，那么两者有什么不同呢？

首先，让我们回顾一下 MCP 是什么。MCP 即 Model Context Protocol，是一个通用标准，让 AI 应用能够连接外部工具和数据，比如我们的数据库或 GitHub。

两者都很有用，而且它们完全不构成竞争。它们回答的是两个不同的问题。

MCP 将 Agent 连接到外部世界。它回答的问题是“Agent 能触达什么？”它赋予 Agent 双手。

Agent Skills 教会 Agent 我们的工作方式。它们回答“Agent 应该怎么做这件事？”这个问题。它们赋予 Agent 专业知识，使其遵循我们确切的步骤和确切的格式。

所以，一个提供触达能力，另一个提供专业知识。

为了便于理解，让我用表格列出 Agent Skills 和 MCP 之间的区别。

对比点Agent SkillsMCP
提供什么专业知识、我们的步骤和格式触达能力、与外部系统的连接
由什么构成一个包含说明的文件夹，有时还有脚本一个运行中的程序，提供工具和数据
回答什么问题这件事应该怎么做？Agent 能触达什么？
需要运行服务器否是
最适合流程、格式、风格、检查清单数据库、应用、实时数据、操作

在实际工作中，我们经常同时使用两者。MCP 将 Agent 连接到我们的问题跟踪系统，而一个 Skill 告诉它我们团队如何撰写问题。

这个领域还有第三个组成部分，其构建方式几乎与 Skill 完全一样。OKF（Open Knowledge Format，开放知识格式）将关于我们数据的知识写成一个纯 markdown 文件文件夹，让 Agent 知道我们的表到底意味着什么。我们有一篇详细介绍 什么是 OKF（Open Knowledge Format）？ 的博客，解释了它在这两者之中的定位。

保持更新： 订阅我们的 新闻通讯，将我们最新的 AI 和机器学习博客直接发送到您的收件箱。

一个真实的例子

学习这个的最好方法是通过一个例子。让我们使用之前的

weekly-report

Skill，从头到尾跟踪一个请求。

第 1 步： 会话开始。Agent 只加载可用 Skills 的名称和描述。我们的

weekly-report

描述现在已被它知晓，但指令尚未加载。

第 2 步： 我们输入：“准备本周的团队更新。”

第 3 步： Agent 将我们的句子与它掌握的描述进行比较。我们的描述提到了“每周报告或团队更新”，所以匹配成功。

第 4 步： Agent 现在读取

SKILL.md

的完整正文。此时，它学会了三个标题、单行规则、顶部的总数统计，以及绝不包含工单编号的规则。

第 5 步： 它按照这些步骤，以我们确切的格式生成报告。

在这里，我们可以注意到最棒的部分。我们从未提及格式。我们从未提及标题。我们从未提醒它工单编号的事。我们在几周前就把所有这些写下来了，而 Agent 在恰当的时机自行应用了它们。

这样，我们就可以使用 Agent Skills 来解决一个有趣的问题：永久地教会 Agent 我们的工作方式，而无需反复重复自己。

我们有一个关于 AI Agent、上下文工程和模型上下文协议（MCP）的完整课程——请查看 Outcome School 的 AI 和机器学习课程，深入学习所有这些内容。

Agent Skills 的重要性

现在，我们已经了解了 Agent Skills 的工作原理。接下来看看它们为什么重要。

  • 一次编写，永久使用。 我们不再在每次对话中重复相同的指令。
  • 桌面保持整洁。 由于渐进式披露，深层知识在被使用之前几乎不占用任何成本。
  • 团队知识得以共享。 一个 Project Skill 能把一个人的经验变成整个团队自动获得的东西。
  • 无需编程。 一个 Skill 就是纯文本文件中的平实英文。任何能写出清晰步骤的人都可以编写一个。
  • 它们是可移植的。 因为格式是开放的，而且只是一个文件夹，同一个 Skill 可以在支持它的不同工具之间通用。
  • 它们可以组合。 Agent 可以在同一个任务中组合多个 Skill，用一个负责格式，另一个负责检查。

我们必须注意的事项

Skills 会改变 Agent 的行为，所以我们必须谨慎使用。

一个 Skill 可以运行代码。 如果 Skill 文件夹中包含脚本，Agent 就可以运行它。这就像在电脑上安装任何程序一样。因此，我们必须只使用来自可信来源的 Skills，并且在使用前先阅读它。

模糊的描述等于浪费的 Skill。 这是最常见的错误。我们写好了指令，但描述没有说明何时使用它们，所以这个 Skill 永远不会被触发。如果一个 Skill 似乎被忽略了，原因几乎总是出在描述上。

太长和太模糊一样糟糕。 正文只应包含 Agent 自己无法猜到的内容，也就是我们的步骤、格式和规则。它不应解释 Agent 已经掌握的通用知识。紧凑的 Skill 胜过冗长的 Skill。

一个 Skill，一个任务。 把所有东西都塞进一个巨大的 Skill 里看似很诱人，但我们绝不能这样做。许多小而专注的 Skill 匹配效果更好，加载也更少。

在这里，我们可以看到规则很简单：让每个 Skill 保持小而具体，为 Agent 编写描述，并且只信任我们读过的 Skills。

总结

让我们快速回顾一下所学的内容。

  • Agent 不了解我们团队的流程、格式和规则，所以我们不得不一次又一次地重复输入它们。
  • 我们不能简单地把所有内容都保持加载状态，因为 Agent 的上下文窗口是有限的。
  • Agent Skill 是一个包含指令的文件夹，还可以选择性地包含脚本和文件，Agent 只在任务需要时才自行加载它。
  • 该文件夹需要一个名为 SKILL.md 的文件，其中包含带有名称和描述的 frontmatter，以及包含指令的正文。
  • 描述就是触发器。Agent 用它来决定何时应用该 Skill。
  • 渐进式披露分为三个层级：名称和描述始终加载，完整指令在匹配时加载，额外文件仅在需要时加载。
  • 一个 Skill 可以携带脚本，因此精确且可重复的工作每次都能以相同的方式运行。
  • 个人技能（Personal Skills）存放在我们的主目录中，而项目技能（Project Skills）存放在项目里，并会同步给整个团队。
  • 创建一个技能无需安装，也无需写代码。一个文件夹加一个 SKILL.md 文件就是一个完整的技能。
  • 编写技能的最佳方式，是把它写给一位能力强的新队友看：跳过他们已经知道的内容，只记录我们特有的东西。
  • MCP 赋予 Agent 触达能力，而技能赋予 Agent 专业知识。我们常常把两者结合使用。

这就是 Agent Skills：一个简单的文件夹，把我们自己的工作方式变成 Agent 能够理解并自主运用的东西。

常见问题

Agent Skills 是谁创建的？

Agent Skills 由 Anthropic 于 2025 年 10 月推出。该格式是开放的，任何人都可以编写技能，任何人也都可以使用技能。由于技能只是一个包含

SKILL.md

文件的文件夹，同一个技能可以在所有支持该格式的不同工具中使用。

为什么我的 Agent Skill 没有被 Agent 使用？

原因几乎总是描述不够清晰。Agent 会将我们的请求与每个技能的描述进行比较，来决定何时使用某个技能。如果描述没有清楚说明该技能做什么、何时使用，那么即使技能的指令写得再好，它也永远不会被触发。

添加很多技能会填满上下文窗口吗？

不会。在开始时，Agent 只加载每个技能的名称和描述，每个技能大约消耗一百个 token。因此，五十个技能总共大约消耗五千个 token。技能的完整指令只有在请求匹配到它时才会被加载。

一个 Agent 能在单个任务中使用多个技能吗？

可以。技能是可以组合的，Agent 可以在单个任务中结合使用多个技能。例如，它可以用一个技能处理格式，用另一个技能执行检查。此外，许多小而聚焦的技能比一个巨型技能匹配得更好、加载得更少。

使用来自互联网的 Agent Skills 安全吗？

只有在我们信任来源的情况下才安全。技能文件夹可以包含脚本，而 Agent 可以运行它，这就像在我们的电脑上安装程序一样。因此，我们必须只使用来自可信来源的技能，并且在使用前先阅读技能内容。

目前就到这里。

谢谢

Amit Shekhar，Outcome School 创始人

你可以通过以下方式与我联系：

关注 Outcome School：