Claude Skills 是什么？和插件、MCP 有什么区别

一句话定义：文件夹 + SKILL.md

Claude Code 官方文档的写法是：创建一个 SKILL.md，里面写说明，Claude 在相关时使用它，你也可以用 /skill-name 直接调。它不是一段提示词， 是一个目录——目录里除 SKILL.md 之外还可以放参考文档、示例和脚本。 官方给的结构长这样：

my-skill/
├── SKILL.md        （必需：概览与导航）
├── reference.md    （详细参考资料，需要时才读）
├── examples.md     （用例，需要时才读）
└── scripts/
    └── helper.py   （工具脚本，执行，不读入上下文）

三个部分各有分工：frontmatter 决定它什么时候被看见，正文 是 Claude 照着做的说明，附带文件是正文指向的深层资料。官方建议把 SKILL.md 控制在 500 行以内，细节挪到单独文件里——原因在下面「渐进式加载」。

它放在哪，决定谁能用

官方文档里列了七八种位置，实际会碰到的就三个：个人目录 ~/.claude/skills/<skill-name>/SKILL.md（这台机器上所有项目都能用）、 项目目录 .claude/skills/<skill-name>/SKILL.md（只在这个仓库里生效， 提交进版本控制团队就都有了）、以及插件里的 <plugin>/skills/<skill-name>/SKILL.md（用的时候带插件前缀， 形式是 /plugin-name:skill-name）。此外还有企业托管设置目录、 --add-dir 附加目录、和从 claude.ai 账户同步下来的一类。

位置不只是「放哪」，它还决定优先级：同名时企业覆盖个人、个人覆盖项目； 你写的 skill 会覆盖同名的自带命令，但不会覆盖它的别名。装之前先想清楚这是 「我这台机器上要用」还是「这个仓库的人都要用」，答案不一样，放的地方也不一样。

frontmatter：名字、描述，和几个可选的开关

文件第一行的 --- 之间是 YAML。所有字段都是可选的，官方唯一建议写的是 description——Claude 就靠它判断「这个请求该不该用这个 skill」。 name 决定你在 / 菜单里输入的命令名，不写就用目录名。 另外几个常见开关（都来自官方字段表）：

• disable-model-invocation: true：只允许你手动调，Claude 不能自己决定用。 有副作用的事（部署、发消息、提交）该这么写。
• allowed-tools：调用这个 skill 的那一轮，列出的工具免确认； 你发下一条消息时授权就清掉。
• context: fork：把 skill 丢进子代理的隔离上下文里跑， 主对话只收结果。
• paths：只在处理匹配这些 glob 的文件时才自动加载。

一个容易误解的点：disable-model-invocation: true 打开后， 描述也不进上下文了。好处是不占日常开销，代价是 Claude 自己发现不了它， 你必须记得输入 /name。

Agent Skills 是什么？就是这套东西的标准名

Claude Code 的 skills 遵循 agentskills.io 上的 Agent Skills 开放标准，这套标准适用于多个 AI 工具。Claude Code 在自己这边加了几项扩展： 控制谁可以调用（disable-model-invocation、user-invocable）、 在子代理里执行（context: fork）、动态上下文注入（正文里的命令会在渲染时先跑）。 这意味着两件事：只写标准内字段的 skill，换个客户端也能用；反过来说， 用了 Claude Code 扩展字段的 skill 拿到别处就只是普通说明，那个字段不会生效。 官方打 claude.ai 上传包时校验很严——带了标准不允许的字段，会直接报错而不是忽略。

渐进式加载：为什么不占上下文

这是 skill 和「把规则全塞进 CLAUDE.md」最大的区别。官方文档把加载分成三段：

1. 平时：每个回合只有 skill 的名字和描述在上下文里，正文不在。 代价是描述有预算——按模型上下文窗口的 1% 缩放，超了就先裁掉你最少用的那些。
2. 调用时：渲染后的 SKILL.md 作为一条消息进入对话， 并在后续轮次保留。注意它不会重读文件，所以你写的应该是「整个任务期间都成立的指令」， 不是一次性的步骤。
3. 需要时：reference.md 这类大文件 Claude 按需去读， scripts/ 里的脚本是执行而不是读入——所以塞一份 300 行的 API 文档不心疼， 但把同一份文档摊进正文就很不划算。

官方还提了一句很准的判断标准：当你不断把同样的说明、检查清单或多步骤流程粘进对话， 或者 CLAUDE.md 的某一段已经从「事实」演变成了「流程」，就该拆成 skill。

三层来源，装之前先分清楚

中文语境里「Claude Skills」这个词把三种东西混在了一起，这是大部分困惑的来源。

分清这三层，能省掉两类白折腾：一是以为装了官方 skill 就懂了你的项目约定—— 官方那批是通用能力，项目约定得你自己写进项目 skill 或 CLAUDE.md； 二是拿社区目录当质量排名——它衡量的是有人收藏过，不是装完有没有用。

四者边界表：skill / plugin / MCP / subagent

这四个词经常被当成同一层的选项，其实不是。skill 是文件，plugin 是装的单元， MCP 是连接协议，subagent 是另一种上下文。下表前三列是官方文档里的机制； 最后一列「典型误用」是我按机制推出来的，不是文档原文。

判断清单：什么时候上 MCP

把「该写 skill 还是该连 MCP」拆成五个问题，按顺序问，第一个命中的就是答案。

1. 你要的是「做法」还是「数据或操作」？ 做法（步骤、检查项、代码风格、评审口径）→ skill。 数据或操作（要读数据库、要建 PR、要看监控）→ MCP server。
2. 你是不是正在把另一个工具里的内容复制进聊天？ 是 → 该连 MCP server。官方文档就是这么划线的：当你要从问题跟踪器或监控面板里复制数据时，去连一个服务器。
3. 这条规则必须每次发生、不允许模型忘掉？ 是 → hook，不是 skill。官方的处理建议很直接：必须每次都成立的规则挪进 hook， 因为 hook 在事件发生时每次都运行，而 skill 靠模型遵守。
4. 输出很脏很长、你不想让它在主对话里？ 是 → subagent。非 fork 子代理从干净上下文开始，只回一份摘要。
5. 你要装的是「一整套」还是「一条说明」？ 一整套（含 hooks、agents、MCP）→ plugin。只有一条说明 → 直接写 skill，别包一层。

再强调一次：skill 和 MCP 不是二选一。MCP 提供工具，skill 提供用工具的做法—— 一个 skill 里可以明确要求先查 issue、再改代码、最后建 PR，工具从 MCP 来，流程从 skill 来。 官方那条 mcp-server-dev 就是典型：它本身是个插件，里面装的是教 Claude 搭 MCP 服务器的 skill。

官方已有中文文档，这页不重复它

实话先说：code.claude.com/docs/zh-CN/skills 是 Anthropic 官方的简体中文文档， frontmatter 每个字段、七种加载位置、排错步骤都写到了，质量不差。这页正文里的机制描述， 我逐条对照的就是它——2026-10-19 核对。

所以这页刻意不做三件事：

• 不抄字段表。需要逐字段查的时候，看官方那张表，别看我转述。
• 不写安装步骤。那是安装那页的活，塞进这页只会把搜索意图搅混。
• 不给没有实测过的数字。这页没有「装完省了多少 token」这类数，因为我没跑过对照。

那这页的价值在哪？官方文档是按「功能」组织的：这里是 skills，那里是 plugins，再那边是 MCP， 每一页都假设你已经知道自己要找什么。而这页是按「选择」组织的——三层来源怎么分、 四者边界在哪、什么情况下别用。文档告诉你有什么，这页告诉你该挑哪个。

什么情况下别用 skill

• 规则必须每次执行。用 hook。skill 的内容在压缩后还可能被丢掉， 靠它做「绝对不允许」的守门是不靠谱的。
• 要实时数据或要写回外部系统。用 MCP server。skill 只是文件， 它没法替你连数据库。
• 输出量大且只用一次。用 subagent。你要的是一次性的隔离， 不是一个可以复用的流程。
• 就三句话能说清、只给一个人用。写进 CLAUDE.md 更省事。 skill 的收益来自「重复使用 + 按需加载」，两样都不占，就不值得建目录。
• 你只是想要一个 star 数高的东西撑场面。那别装。skill 的上下文成本 按每个 skill 的描述算，装十个用不上的是纯亏。

四个具体的坑

这四个都是机制层面的，不是「运气不好」，官方文档里都有对应条目。

1. skill 一多，描述被裁，触发不了。描述列表按模型上下文窗口的 1% 缩放， 超预算时从你最少用的 skill 开始删描述，关键词就在被删的那部分里。 用 /doctor 估列表成本，用 /skill-doctor 看每个 skill 被用了几次、值不值得留。
2. frontmatter 写错，skill 还能调，但自动触发废了。YAML 解析失败时 Claude Code 仍加载正文，只是所有字段为空——/skill-name 照常能用， Claude 却匹配不到你的 description。用 --debug 看解析错误， 或者对目录跑 claude plugin validate 找坏文件。
3. 长对话压缩后，早调用的 skill 内容会消失。压缩时每个被调用的 skill 只保留最近一次调用的前 5,000 个 token，总预算 25,000，从最近调用开始填。 所以关键指令写进 SKILL.md 开头，别指望中间段落活到最后。
4. 把它藏在 disable-model-invocation 后面，然后抱怨它从不触发。 这个字段会让描述不进上下文，Claude 根本不知道它存在。手动工作流可以这么设， 想让它自动生效就别设。

接着看

• Skills 还是 Plugins？一张表说清怎么选

  六个维度逐项对比，加三种组合方案和「选错的代价」。

  选择 · 2026-10

• Claude Code Skills 安装：三种方法 + 常见报错

  装到哪个目录、项目级还是全局、装完为什么要重开会话。

  安装 · 2026-10

• 值得装的 Claude Code Skills：按场景选，不按 star 排

  只收装过、跑过、还能继续用的，每条写清不适合谁。

  清单 · 2026-10

这一页的依据

• code.claude.com/docs/zh-CN/skills ——文件结构、frontmatter 字段、加载位置与优先级、描述预算、内容生命周期、排错条目。
• code.claude.com/docs/zh-CN/plugins/overview ——插件是什么、包含什么、独立组件与插件的分工、启用后的上下文成本。
• code.claude.com/docs/zh-CN/mcp ——MCP 用途、安装作用域、工具搜索与延迟加载、提示注入提醒。
• code.claude.com/docs/zh-CN/sub-agents ——子代理的独立上下文、定义位置、工具限制，以及「要复用流程请改用 skills」。
• github.com/anthropics/skills ——官方 skills 仓库：2026-10-19 取数 182,075 stars，skills/ 下 19 个目录。
• github.com/vercel-labs/skills ——跨 agent 安装器：2026-10-19 取数 35,548 stars、MIT、建库 2026-01-14。

本页没有做安装与运行实测，因此不给耗时、token 差值这类数字。星数、目录数与字段名均取自 2026-10-19 的官方文档与 GitHub API，过期后请以文档为准。