Agent skill到底是什么？与MCP有何区别

Agent skill 的实际含义

Agent skill 是磁盘上的一个目录，其中包含名为 SKILL.md 的文件。该文件包含名称、简短描述，以及使用普通 Markdown 编写的说明。Agent 会在启动时加载描述，只有当您的请求与该描述匹配，或您按名称调用该 skill 时，才会读取说明。skill 的其他大多数特性都由这两点决定。

该目录可以包含不止一个文件。Agent Skills 规范定义了 3 个可选目录：scripts/ 用于存放 Agent 运行的代码，references/ 用于存放 Agent 在需要时读取的文档，assets/ 用于存放模板和数据。这些目录都不是必需的。目录中仅包含 SKILL.md 也构成一个完整的 skill。

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

描述部分最容易被低估。在 Agent 决定是否打开 skill 之前，它只能看到描述。因此，描述必须说明该 skill 的用途和适用场景，并使用人们实际会输入的措辞。

为什么技能在使用前几乎不产生开销

这是理解该格式价值的关键。重点在于上下文，而不是功能。加载分多个阶段进行，规范将其称为渐进式披露。

启动时，代理只加载每个已安装技能的 name 和 description，不会加载其他内容。Agent Skills 规范建议，每个技能约占 100 tokens（截至 2026 年 10 月发布的指导）。安装 12 个技能，消耗的上下文大约相当于一个较长段落。

当请求与某个描述匹配时，代理会读取该 SKILL.md 的正文。规范建议将正文控制在 5,000 tokens 以内，并将文件控制在 500 行以内。此时，references/ 和 scripts/ 中的文件仍然不会产生开销。只有当指令要求代理读取某个参考文件时，该文件才会加载。捆绑脚本则不同：代理通过 shell 运行脚本，因此脚本源代码不会进入上下文窗口，只有脚本输出会进入。

再与人们最先想到的方案比较：使用一个庞大的提示词。系统提示词或始终启用的指令文件中的每一行，都会在每次请求、每个会话中产生开销，无论任务是否需要这些内容；它们还会与实际问题争夺注意力。即使只是询问当前时间，也要支付 10,000 tokens 的常驻指令成本。12 个技能在闲置时约占 1,200 tokens，只有需要某项技能的任务才会使上下文扩展。这就是使用技能的全部理由，也是小型技能库优于更长提示词的原因。

有一个容易被忽略的注意事项。技能加载后，其正文会在本次会话的剩余时间内保留在上下文中，因此较长的 SKILL.md 会持续产生开销，而不是只产生一次。将详细内容移到 references/ 中并不是为了整洁，而是让机制按设计方式运行。

代理技能不是工具调用

工具（也称为函数调用）是模型可以调用的对象。工具执行框架会向模型发送一个架构，其中包含名称、描述和参数结构。模型发出调用后，您的代码执行该调用，结果再以消息形式返回。工具负责执行操作。这个交互的两端都属于负责在模型周围运行循环的程序，即执行框架；执行框架还会在启动时读取技能描述，并决定何时打开某个技能。

技能本身不会执行任何操作。代理读取技能后，使用已有工具执行任务。模型不能像向工具传递参数那样向技能传递参数。技能可以做的是告诉模型应使用哪些工具、按什么顺序使用，以及之后检查哪些内容。将任务交给第二个代理就是最清楚的例子：一个 Claude Code 会话已经可以向另一个会话发送消息，而技能负责记录何时值得这样做，以及应发送哪些内容。

简而言之：工具为代理提供新的能力，技能主要让代理学会判断如何使用已有能力。如果技能确实增加了某种能力，它也是通过代理使用已有 shell 运行的附带脚本来实现的。如果某个步骤每次都必须生成准确且经过验证的结果，应使用工具或脚本。如果某个步骤需要持续采用相同的思路，应使用技能。技能完全可以只提供判断，却仍然成为您最常使用的工具之一。Ponytail 会促使编码代理采用能够工作的最小改动就是这种情况：它没有增加任何新能力，只改变代理使用已有能力的方式。这种判断也可以指向相反的方向。unlazy 技能通过遍历深度树，防止代理过早宣布任务完成采用了相同的方法，但目标是提高全面性，而不是限制改动。

Agent skill 不是 MCP 服务器

MCP（model context protocol）是一种用于将 agent 连接到外部系统的协议。MCP 服务器是运行该协议并向 agent 暴露工具的进程。它通常需要配置、凭据，以及本地命令或网络端点。skill 则是一个包含 Markdown 文件的目录。它不包含进程、端口或协议。

两者的上下文开销也不同。MCP 服务器暴露的每个工具都包含名称、描述和参数架构。在预先加载这些工具的客户端中，无论是否使用，这些内容都会在整个会话中保留于请求内。Claude Code 默认已不再采用这种方式：截至 October 2026，其工具搜索默认启用，因此会话开始时只加载工具名称和服务器说明；Claude 搜索工具时才会加载完整定义。skill 在未使用时只是一行文本。

两者可以互补，最佳方案通常同时使用二者。MCP 服务器提供访问能力。skill 提供操作流程：针对团队的实际工作流，应调用哪些工具、按什么顺序调用，以及什么样的结果才算良好。如果自行托管，在 VPS 上运行 MCP 服务器介绍了这一部分。

Agent skill 不是系统提示词，也不是 AGENTS.md

两者都是 Markdown 中的指令，因此产生混淆很正常。区别在于它们的加载时机。AGENTS.md、CLAUDE.md 和系统提示始终处于启用状态。技能按需启用。Claude Code 的 输出样式位于始终启用这一端的最末端，因为选择一种样式会直接修改系统提示，因此它会影响会话中的每条回复，包括任何技能都不会处理的回复。

判断标准只有一个：如果任务与这段内容无关，忽略这段内容是否会导致错误？统一的文档风格、构建命令和分支命名规则适用于所有任务，因此应放在始终生效的文件中；每月执行两次的发布检查清单并不适用于所有任务，因此应放在 skill 中。当始终生效文件中的某个部分逐渐变成编号流程时，就说明应将其移出。

这些文件也有各自的约定，需要正确使用。请参阅AGENTS.md 中应包含哪些内容，以及哪些内容应放在人类维护的文件中和解释代码库结构的 design.md，这正是我们使用的两类文件。

最小技能的形式

在 Claude Code 中，个人技能存放在 ~/.claude/skills/<name>/SKILL.md，适用于您的所有项目。项目技能存放在 .claude/skills/<name>/SKILL.md，并提交到 git，因此在该仓库中工作的每个人和每个代理都能使用这些技能。GitHub Copilot 和 VS Code 会从 .github/skills/、.agents/skills/ 以及 .claude/skills/ 读取项目技能。目录中的文件内容相同。

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

这就是一个完整的技能。目录名称会成为您输入的命令，因此此技能的命令是 /restore-drill。在 Claude Code 中，/skills 菜单会列出已安装的技能，这是确认文件已被识别的最快方式。如果该技能未出现在菜单中，请先检查名称：文件必须命名为 SKILL.md。此外，Agent Skills 规范要求名称只能包含小写字母、数字和单个连字符，并且必须与目录名称一致。将同一流程写成代理可以重复执行的操作步骤，是 VPS 上的定期 restic 备份 的自然补充；备份正在运行并不等于备份可以恢复。

应将技能改为脚本的情况

每次都有唯一正确答案的步骤都应写成脚本。技能本身只需用几行说明何时运行脚本，以及如何读取输出。这样做有两个原因，而且都很实际。

首先，脚本源码不会进入上下文窗口。一个 300 行的解析器只占用其输出所需的上下文，而将相同逻辑写成 Markdown 指令时，每次加载技能都会占用完整篇幅。

其次，脚本每次都能给出相同答案。如果要求模型每次运行时重新推导相同的日志解析规则，在状态不佳时，结果可能会略有不同。等到两个数字不一致时，您才会发现问题。

因此，应按工作类型拆分任务。“解析 CSV，并打印总数与明细项不匹配的每一行”应写成脚本。“查看脚本打印的行，并说明哪些行可能存在数据录入错误”应写成技能指令。将判断逻辑保留在 Markdown 中，将确定性逻辑放入代码中，这与构建一个无需您监视即可由代理运行的循环遵循的是同一原则。

为什么我的 skill 从不触发？

因为它的 description 只说明 skill 的作用，却没有说明何时使用它。代理只能根据这一行来匹配您的请求。“帮助处理数据库工作”无法与任何具体请求匹配。“对 staging 数据库执行架构迁移。用户请求迁移表、添加列或更改架构时使用”包含用户实际会输入的词，因此可以触发。

相反的问题是 skill 持续触发。例如，“用于此仓库中的任何代码更改”会匹配所有内容，因此每个任务都会加载正文，之后一直占用会话上下文。请将描述限定为您真正需要的场景。在 Claude Code 中，您还可以在 frontmatter 中设置 disable-model-invocation: true，这样可以阻止自动加载，但在您输入其名称时仍可使用该 skill。

第三个问题是 skill 重复了工具的功能。如果 MCP server 已经提供了某个 API，而指令仍要求代理 curl 该 API，或者 harness 已经提供搜索工具，指令却要求代理遍历文件进行 grep，那么您得到的只是更慢的路径，以及两套可能互相冲突的指令。删除重复内容，改为描述目标。

不要猜测自己遇到的是哪一种问题。在全新会话中使用相同的提示运行两次：一次启用该 skill，一次关闭该 skill，然后比较答案。全新会话很重要，因为您编写 skill 的那个会话已经包含 skill 所说的全部内容，这会掩盖书面版本中的缺口。Anthropic 的 skill-creator plugin 可在 Claude Code 中自动完成这项比较，包括生成应该触发和不应该触发该 skill 的提示，并衡量每种提示的实际触发频率。如果 skill 确实加载了，但代理仍未按其要求执行，那么问题不在描述中；接下来应查看代理已读到指令却仍然偏离执行的原因。

这是某一家供应商的格式，还是一项标准？

Anthropic 于 2025 年底发布了该格式，随后将其作为开放标准发布在 agentskills.io 上。截至 2026 年 10 月，该规范定义了必需的 name 和 description 字段、可选的 license、compatibility、metadata 和 allowed-tools 字段、3 个可选目录，以及分阶段加载行为。该项目还提供了参考验证器，因此 skills-ref validate ./my-skill 可在共享文件夹前根据规范对其进行检查。

真正能说明问题的是客户端列表。Claude Code、Cursor、OpenAI Codex、Gemini CLI、GitHub Copilot、VS Code、Goose、OpenHands 和 opencode 等工具都会读取同一个文件夹。Microsoft 在 github.com/microsoft/skills 中以该格式发布自己的技能，并提供名为 Skill Recorder 的桌面工具。该工具会记录你完成一次任务的过程，将其重构为一个意图和按顺序排列的步骤，然后将结果写入技能文件。供应商构建的记录工具，其输出格式却遵循其他厂商制定的规范，这表明该格式已经不再只是某个产品的功能。

首先写什么

不要先规划技能库。等到您第三次发现自己把同一段说明粘贴到聊天中时，再将这段文字移到 SKILL.md，并删除原来的粘贴内容。只有已经亲身感受到的重复，才是值得保留某项技能的可靠触发条件。搜索流程是一个很好的起点，使用您自己的 SearXNG 实例支持的搜索技能展示了其基本形式。

有两个习惯可以让技能库保持良好状态。安装任何不是您编写的技能前，都应阅读其全部内容，包括脚本，因为技能包含代理将遵循的说明以及可能运行的代码：应像安装陌生人提供的软件一样谨慎对待。还应将凭据放在文件夹之外，因为技能是会被提交和共享的文本文件。让机密信息远离代理介绍了这些值应存放的位置，今年学习代理的路线图则将技能与其他配置步骤一并安排了顺序。

FAQ

agent skill 与 MCP 服务器有什么区别？

MCP（模型上下文协议）服务器是一个运行中的进程，通过协议向 agent 暴露工具。因此，它需要配置和凭据；除非客户端延迟加载工具定义（Claude Code 现在默认采用这种方式），否则完整的工具定义会在整个会话中占用上下文。agent skill 是一个包含 SKILL.md 文件的目录，不运行进程，也不使用协议；在 agent 决定读取它之前，通常只占用约 100 个 token。使用 MCP 服务器可让 agent 访问某个系统。使用 skill 可告诉 agent 如何正确使用该访问权限。许多环境会同时使用两者。

agent skill 只能用于 Claude Code 吗？

不能。Anthropic 制定了这种格式，随后将其作为开放标准发布到 agentskills.io。同一个目录也可由 Cursor、OpenAI Codex、Gemini CLI、GitHub Copilot、VS Code、Goose、OpenHands 及其他客户端读取。不同之处在于各客户端查找目录的位置，以及支持哪些额外的 frontmatter 字段。Claude Code 读取 ~/.claude/skills/ 和 .claude/skills/；GitHub Copilot 和 VS Code 则读取仓库中的 .github/skills/、.claude/skills/ 或 .agents/skills/。SKILL.md 文件本身可以在这些客户端之间直接迁移，无需修改。

安装多少个 skill 后会开始拖慢速度？

限制因素是启动预算，而不是数量。每个已安装的 skill 都会贡献名称和描述。按照规范发布的指导，每个 skill 大约占用 100 个 token。因此，30 个 skill 在实际使用前约占用 3,000 个 token。首先受到影响的通常是匹配能力，而不是速度：描述相互重叠的 skill 越多，模型越难选择正确的 skill。编写互不重叠的描述，并删除不再使用的 skill。

这条指令应该放在 skill 中，还是放在 AGENTS.md 中？

判断它是否适用于仓库中的每个任务。构建命令、项目规范和命名规则适用于所有任务，因此应放在始终加载的文件中；该文件的作用就是每次都加载。偶尔执行的流程（例如发布检查清单或恢复演练）应放在 skill 中。这样，在不需要该流程的任务中，只需承担一行描述的开销。如果 AGENTS.md 中的某个部分已经扩展成编号步骤，通常说明它是一个应当移出的 skill。