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

Agent skill 的实际含义

Agent skill 是磁盘上的一个目录，其中包含名为 SKILL.md 的文件。该文件包含名称、简短描述，以及使用普通 Markdown 编写的说明。Agent 在启动时加载描述，只有当您的请求与该描述匹配时，才会读取说明。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 个 token（截至 August 2026 的公开指导）。安装十几个技能，消耗的上下文大约相当于一个较长的段落。

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

现在将其与人们最先采用的方式进行比较：一个庞大的提示词。系统提示词或始终启用的指令文件中的每一行，都会在每个请求、每个会话中产生开销，无论任务是否需要它们，而且还会与实际问题争夺注意力。10,000 个 token 的常驻指令，即使只是询问时间，也必须支付这笔开销。十几个技能在未加载时约占用 1,200 个 token，只有执行需要它们的任务时才会扩展。这就是采用技能的完整理由，也是小型技能库优于更长提示词的原因。

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

Agent 技能不是工具调用

工具也称为函数调用，是模型可以调用的对象。工具框架会向模型提供一个 schema，其中包含名称、描述和参数结构。模型发出调用后，您的代码执行该调用，结果再作为消息返回。工具用于执行操作。

技能本身不会执行任何操作。Agent 读取技能内容，然后使用已有的工具执行任务。模型不能像向工具传递参数一样向技能传递参数。技能可以告诉模型应使用哪些工具、按什么顺序使用，以及之后需要检查什么。

简而言之，工具为 Agent 提供新的能力，技能则让 Agent 能够对已有能力作出判断。如果某个步骤每次都必须生成经过验证的精确结果，应使用工具或脚本。如果某个步骤需要持续一致地采用相同的思考方式，应使用技能。

Agent skill 不是 MCP 服务器

MCP（模型上下文协议）用于将 agent 连接到外部系统。MCP 服务器是运行该协议并向 agent 提供工具的进程。它通常需要配置、凭据，以及本地命令或网络端点。skill 则是一个包含 Markdown 文件的目录。其中没有进程、端口或协议。

两者的上下文成本也不同。MCP 服务器提供的每个工具都包含名称、描述和参数架构。默认情况下，这些内容会在整个会话中随请求发送，无论是否实际使用。部分客户端已开始按需获取工具架构，但预先加载仍是常见做法。skill 在闲置状态下只占一行文本。

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

代理技能不是系统提示，也不是 AGENTS.md

两者都是 Markdown 格式的指令，因此产生混淆很正常。AGENTS.md、CLAUDE.md 和系统提示始终生效。技能按需生效。

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

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

最小技能的形式

在 Claude Code 中，个人技能存放在 ~/.claude/skills/<name>/SKILL.md，适用于您的所有项目。项目技能存放在 .claude/skills/<name>/SKILL.md，并提交到 git，因此该仓库中的每个人和每个代理都可以使用这些技能。GitHub Copilot 和 VS Code 则从 .github/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，目录名称必须只包含小写字母、数字和单个连字符。将同一操作写成代理可以重复执行的流程，是 VPS 上的定期 restic 备份 的自然补充，因为备份正在运行并不等于备份可以恢复。

应将技能改为脚本的情况

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

第一，脚本源码不会进入上下文窗口。一个 300 行的解析器只会占用其输出所需的上下文空间，而同样的逻辑如果写成 Markdown 指令，技能每次加载时都要占用完整长度。

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

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

为什么我的 skill 从未触发？

因为其中的 description 只说明 skill 的作用，却没有说明何时使用它。代理只能根据这一行将其与您的请求进行匹配。“处理数据库工作”无法明确匹配任何请求。“针对 staging 数据库运行 schema migration。用户要求迁移表、添加列或更改 schema 时使用”包含用户实际会输入的词，因此可以触发。

相反的问题是 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 的提示，并衡量每类提示的实际触发频率。

这是某个供应商自有的格式，还是一种标准？

Anthropic 于 2025 年末发布了这种格式，随后将其作为开放标准托管在 agentskills.io。截至 2026 年 8 月，该规范定义了必需的 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 server 有什么区别？

MCP（model context protocol）server 是通过协议向 agent 提供工具的运行中进程，因此需要配置和凭据。其工具定义通常会在整个会话中占用上下文，无论是否实际使用。agent skill 是一个包含 SKILL.md 文件的目录，不运行进程，也不使用协议。在 agent 决定读取它之前，只占用约 100 个 token。使用 MCP server 可让 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/。SKILL.md 文件本身可在这些客户端之间直接迁移，无需修改。

安装多少个 skill 后才会影响性能？

限制因素是启动预算，而不是数量。根据规范发布的指导，每个已安装的 skill 会贡献其名称和描述，约占 100 个 token。因此，安装 30 个 skill 时，在使用其中任何一个之前就会占用约 3,000 个 token。首先受影响的通常不是速度，而是匹配效果：描述相互重叠的 skill 越多，模型就越难选择正确的 skill。编写互不重叠的描述，并删除已停止使用的 skill。

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

先判断它是否适用于仓库中的每项任务。构建命令、项目规范和命名规则适用于所有任务，因此应放在始终加载的文件中；该文件的目的就是每次都加载。偶尔执行的流程，例如发布检查清单或恢复演练，应放在 skill 中。这样，在不需要它的任务中不会产生开销。AGENTS.md 中已经扩展为编号步骤的部分，通常就是等待迁移的 skill。