什么是智能体技能？与提示词和 MCP 的区别

智能体技能的实际含义

智能体技能是磁盘上的一个文件夹，其中包含名为 SKILL.md 的文件。该文件包含名称、简短描述，以及使用纯 Markdown 编写的说明。智能体在启动时加载描述，只有当您的请求与该描述匹配时，才会读取说明。技能的其他大部分行为都源于这两点。

该文件夹可以包含不止一个文件。Agent Skills 规范定义了 3 个可选目录：scripts/ 用于存放智能体运行的代码，references/ 用于存放智能体按需读取的文档，assets/ 用于存放模板和数据。这些目录都不是必需的。只包含一个 SKILL.md 的文件夹就是完整的技能。

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

人们往往低估描述的重要性。在决定是否打开技能之前，智能体能看到的唯一文本就是描述。因此，描述必须说明技能的作用和使用时机，并且要使用人们实际会输入的措辞。

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

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

启动时，代理只加载每个已安装技能的 name 和 description，不会加载其他内容。Agent Skills 规范建议，截至 2026 年 8 月，这部分每个技能约占 100 个 token。安装十几个技能，消耗的上下文大约相当于一个较长段落。

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

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

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

Agent skill 不是工具调用

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

skill 不会自行执行任何操作。代理读取它，然后使用已有工具采取行动。模型不能像向工具传递参数那样向 skill 传递参数。skill 可以做的是告诉模型应使用哪些工具、按什么顺序使用，以及之后要检查什么。将任务交给第二个代理就是最明显的例子：一个 Claude Code 会话已经可以向另一个会话发送消息；您可以在 skill 中写明什么情况下值得这样做，以及要发送哪些内容。

简而言之：工具为代理提供新的能力，skill 则让代理学会判断如何使用已有能力。如果某个步骤每次都必须生成经过验证的精确结果，应使用工具或脚本。如果某个步骤需要持续采用相同的思路，应使用 skill。skill 可以只包含判断逻辑，但仍可能成为您最常使用的 skill，正如 Ponytail，它促使编码代理采用能够正常工作的最小改动 所示：它没有增加任何新能力，只改变代理使用已有能力的方式。这种判断也可以指向相反的方向；unlazy skill，它通过遍历 Depth Tree，阻止代理过早宣布任务完成 采用的是同一技巧，只是目标从克制改为彻底。

Agent skill 不是 MCP server

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

两者的上下文成本也不同。MCP server 暴露的每个工具都包含名称、描述和参数 schema。默认情况下，这些内容会在整个会话中随请求发送，无论是否使用。部分客户端已开始按需获取工具 schema，但预先加载仍是常见做法。skill 在未加载时只有一行文本。

两者可以互补，最佳实践通常是同时使用。MCP server 提供访问能力。skill 提供操作流程：针对团队的实际工作流，应调用哪些工具、按什么顺序调用，以及什么结果才算正确。如果您自行托管，在 VPS 上运行 MCP server 会介绍相关内容。

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/ 读取工作区技能。其中的文件相同。

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 数据库执行架构迁移。用户请求迁移表、添加列或更改架构时使用”包含用户实际会输入的词，因此可以触发。

相反的问题是 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 年 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 以该格式发布自己的 skills，并提供名为 Skill Recorder 的桌面工具。该工具会监控您执行一次任务，将其还原为一个意图和一组有序步骤，然后将结果写入 skill。某家供应商构建的记录工具，其输出格式却采用其他厂商定义的规范，这说明该格式已经不再只是某个产品的功能。

首先写什么

不要先规划技能库。等到您第三次发现自己把同一段说明粘贴到聊天中时，再将这段文字移到 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 数量。根据规范发布的指导，每个已安装的 skill 会贡献名称和描述，约占 100 个 token。因此，安装 30 个 skill 后，在使用其中任何一个之前，约需占用 3,000 个 token。首先受到影响的通常是匹配能力，而不是速度：描述相互重叠的 skill 越多，模型就越难选择正确的 skill。请编写互不重叠的描述，并删除不再使用的 skill。

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

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