章节导航 第 12 章 / 共 23 章
第 12 章 第四部分：工程细节

Skills 与插件体系

官方 bundled skills 与自定义技能开发模式、插件目录结构与动态加载缓存机制——Claude Code 的两层扩展架构

Claude Code Skills 插件 扩展机制 SkillTool

12.1 两层扩展架构

Claude Code 有两套扩展系统：Skills（技能）和 Plugins（插件）。它们的区别不只是名字——它们代表了两种完全不同的扩展哲学。

维度SkillsPlugins
本质Prompt 模板 + 脚本代码模块
定义方式SKILL.md Markdown 文件TypeScript/JavaScript 代码
调用方式Slash 命令（/skill-name）自动集成到工具池
权限继承调用代理的权限可定义独立权限
复杂度低（适合 prompt engineering）高（需要编码）
分发.claude/skills/ 目录或插件打包分发/plugin 命令 + 插件市场
数量官方 bundled skills 当前 10 个 + 无限自定义动态加载，数量由 Flag 控制
工具治理disallowed-tools frontmatter 硬移除工具（v2.1.152+）继承 Skill 级治理 + pluginSuggestionMarketplaces 企业 allowlist

简单说：Skills 是”Prompt 即代码”，Plugins 是传统的代码扩展。

比”工具治理”更上游的一刀：来源治理。 上表最后一行讲的 disallowed-tools 管的是技能能用什么工具。托管设置里另有一组键管的是什么样的技能才存在——这是更上游的一刀，且两者不互相替代：

键作用
strictPluginOnlyCustomization含 .agents / .hooks / .mcp / .skills 四个子键，阻止来自用户与项目源的 skills / agents / hooks / MCP servers，把自定义锁定到插件与托管源
disableSideloadFlags拒绝 --plugin-dir、--agents、MCP 服务器这类 sideload 用的 CLI 参数
allowManagedHooksOnly只运行组织下发的 hook（与第 11 章同源）
requiredMinimumVersion / requiredMaximumVersion钉住版本区间，低于最低版本拒绝启动
parentSettingsBehavior决定 SDK / IDE 宿主传入的策略是被采纳还是被丢弃

配套着看：disableSideloadFlags 堵的是命令行这条旁路，strictPluginOnlyCustomization 堵的是用户目录与项目目录这两条主路。三条都关上之后，组织内”一个技能是怎么来到这台机器上的”这个问题就只剩一个答案——来自插件或托管源。这正是 12.5.2 那个坏样本比例之后必须有的收口动作：既然按热度排序靠不住、静态检测会被外观变换绕过，最有效的收敛手段就是把来源本身收窄到可审计的几个。

⚠️ 一个锚点数字：官方 settings-reference 中 scope 为 Managed 的键在 2026-10-19 已达 44 项（第 13 章会给出完整清单）。这个计数本身会变，但”托管设置键在持续膨胀”这个趋势是稳定的——它说明组织侧的可控面在扩大，也说明普通用户读 settings 文档时会越来越难分辨哪些键自己能改。

12.1.1 插件的 plugin.json 架构

2026 年的 Claude Code 插件系统已演进为独立的市场生态。插件通过 /plugin 命令打开市场 UI，用户可以浏览、安装和管理来自插件市场的扩展。

插件本质是一个目录，内含 .claude-plugin/plugin.json 清单文件：

my-plugin/                     # 插件根目录（plugin root），不是 ~/.claude/
├── .claude-plugin/
│   └── plugin.json            # 清单文件（name, version, description）——仅此一个文件
├── skills/<name>/SKILL.md     # 打包的技能（推荐）
├── commands/                  # 扁平 Markdown 技能（legacy，新插件用 skills/）
├── agents/                    # 自定义代理定义
├── hooks/hooks.json           # 事件处理器
├── .mcp.json                  # MCP 服务器配置
├── .lsp.json                  # LSP 服务器配置（代码智能）
├── monitors/monitors.json     # 后台监控
├── output-styles/<name>.md    # 输出风格：改变 Claude 的措辞与格式
├── themes/<slug>.json         # 配色主题（插件主题只读）
├── workflows/*.js             # 工作流：meta 块 + 编排多个子代理的脚本体
├── scripts/                   # 生命周期脚本（约定名，非扫描目录）
├── bin/                       # 可执行文件，插件启用时加入 Bash 的 PATH
└── settings.json              # 插件启用时应用的默认设置

插件将 Skills（以及 Commands、Agents、Hooks、MCP 服务器、LSP 服务器、后台监控）打包为可安装的包。这意味着 Plugins 是 Skills 的分发格式，Skills 是插件的内容子集。用户从单一 Skill 起步，可将其打包为 Plugin 进行分发共享。

⚠️ 官方硬性反模式警告（照抄目录树前必读）：不要把 commands/、agents/、skills/、hooks/ 放进 .claude-plugin/ 目录——只有 plugin.json 属于 .claude-plugin/，其余所有目录必须位于插件根层级。插件根是插件自身的目录（如上例的 my-plugin/），绝不是 ~/.claude/；例如放在 ~/.claude/.mcp.json 的 MCP 配置不会被读取。

这条警告是本章最容易被读者踩中的坑：把子目录与 plugin.json 平铺在 .claude-plugin/ 内，插件会加载失败。

另外两点来自官方的结构约定：settings.json 目前只支持 agent 与 subagentStatusLine 两个键，未知键被静默忽略，且其优先级高于 plugin.json 中声明的 settings；bin/ 不能出现在通过 claude.ai 组织设置分发的顶层插件中。

单 Skill 插件可以省掉 skills/ 目录，把 SKILL.md 直接放在插件根，Claude Code 用 frontmatter 的 name 作为调用名。

四类上一版漏掉的组件（2026-09-29 按官方 components 文档补齐）。目录树里新加的四个目录，性质并不相同，混为一谈会误用：

组件存放形式出现在哪manifest 键
输出风格output-styles/<name>.md/output-style，显示为 <plugin>:<name>outputStyles
配色主题themes/<slug>.json/theme，以文件内 name 显示并标注来源插件experimental.themes
工作流workflows/*.js以 /<plugin>:<name> 运行无（扫描目录）
生命周期脚本scripts/不被扫描，由 hook 按路径调用无

三点值得单独说。其一，输出风格与主题是唯一带 manifest 键的两类——官方原文明示”设置 manifest 键会取代目录扫描”（for either one, setting the manifest key replaces the folder scan），这与 12.1.1 另一处”settings.json 覆盖 plugin.json 的 settings”是同一种”显式声明压过隐式发现”的偏好。其二，插件主题只读：用户在 /theme 里编辑插件主题时，编辑结果另存为副本到用户自己的 themes 目录，插件自带的那份不被改动——这是插件分发物不可变的一个具体切片。其三，scripts/ 是约定而非契约：官方在讲解 hooks/hooks.json 调用 ${CLAUDE_PLUGIN_ROOT}/scripts/format.sh 时专门加了一句，目录名 scripts/ 是约定，Claude Code 并不去找它，hook 是按路径指向文件的。把它和 skills/、commands/ 这类”放进去就被扫描”的目录并列，是这张目录树最容易被误读的地方。

补齐 workflows/ 尤其影响 12.7 的叙事。workflow 的形式是 meta 块加一段编排多个子代理的脚本体，它才是”协议→模块→分发”里”模块”这一层的完整形态——单个子代理是模块，把若干子代理按序编排起来的 workflow 是模块的组合，插件只是两者的分发外壳。

最后一条是校验侧的：v2.1.283 修了 claude plugin validate 放行 outputStyles / themes / monitors / lspServers 路径缺失或指向插件目录之外的插件。这句话反过来读更有用——这四类路径是被校验的，其余组件目录不是。插件作者想在 CI 里挡住路径写错的插件，v2.1.283 起才真正挡得住。

编辑说明：本节基于 agensi.io（2026）和 lobehub 插件参考文档（2026年1月）补充。Plugin 系统的完整 Schema 和 CLI 打包命令请参考 lobehub 插件参考文档。

12.2 内置技能

Claude Code 提供多种内置技能（数量随版本变化，以下为代表性示例），覆盖从代码操作到配置管理的常见场景：

类别技能（内部标识）功能触发条件对外斜杠命令
配置管理updateConfig修改 settings.json用户想更改设置未作为 bundled skill 收录
keybindings自定义快捷键配置用户想改键位未作为 bundled skill 收录
API 指导guideClaudeApiClaude API 使用指导用户问 API 用法/claude-api
代码操作verifyCode代码验证需要检查代码正确性/verify
debugCode调试辅助排查 Bug/debug
项目管理createPlan创建分步实施计划复杂任务需要规划未作为 bundled skill 收录
reviewPRPR 审查代码审查场景/code-review
记忆管理remember审查和组织记忆记忆需要清理（仅 Ant 用户）未作为 bundled skill 收录

技能通过 SkillTool 工具调用，本质上是一个预定义的 prompt 模板——调用技能时，对应的 prompt 被注入到当前对话中，引导模型按照特定的工作流执行任务。

两套清单为什么对不上。 上表的内部标识来自泄漏源码，官方用户可见文档给出的是另一套形态——用户可键入的斜杠命令。官方 bundled skills 当前为（2026-09-11 官方 skills 文档快照）：/doctor、/code-review、/batch、/debug、/loop、/claude-api、/run、/verify、/run-skill-generator、/workflow-authoring。

两份清单只有四项在语义上可对应（guideClaudeApi ↔ /claude-api、verifyCode ↔ /verify、debugCode ↔ /debug、reviewPR ↔ /code-review）。差异的根源是观察视角不同：源码清单记录内部工具名，官方清单记录用户可调用入口；部分内部标识可能已移除或从未对外暴露。读者若要确认”当前版本有哪些内置技能”，应以官方清单为准——打一个 / 就能核验，源码清单做不到。

注意官方措辞：官方原文对 bundled skills 用的是 “such as”（例如），即上列 10 项并非穷举。此外 /workflow-authoring 只在启用 dynamic workflows 时可用，/doctor 自 v2.1.205 起才从内置命令改为 bundled skill。

/claude-api 不是一项，而是一个子命令家族。 上表把它与 /doctor、/verify 并列，容易读成”一个技能、一个入口”。官方对它 的描述是”加载 Claude API 与 Managed Agents 参考材料”，并在其后给出十个子命令，每个带各自的最低 Claude Code 版本：

子命令作用最低版本
migrate把现有 Claude API 代码迁到更新的模型早于 v2.1.221（表内可追溯的最早版本）
upgrade跨大版本升级 Anthropic SDK 依赖（当前为 Python anthropic 0.x → 1.x）v2.1.239+
managed-agents-onboard走一遍新建 Managed Agent 的流程早于 v2.1.221
managed-agents-onboard <url>按某个页面所描述的 Managed Agent 来构建v2.1.290+
managed-agents-onboard <quickstart-name>构建 Console 的某个快速开始模板（如 deep-researcher）；给一个不是模板名的词，Claude 会列出合法名字v2.1.290+
prompt-audit找出 prompts / skills / 工具描述里为旧模型写的指令，以 diff 形式给出修改建议v2.1.221+
cost-optimize剖析 Claude API 开销分布，逐项给出节省建议（prompt caching、裁剪 token、批处理、effort、模型选择）v2.1.247+
build-eval为你的 Claude 应用构建 eval 集v2.1.259+
hillclimb对着已有 eval 迭代改进应用v2.1.259+
preserved-thinking-migration找出你的集成对历史 turn / system prompt / 工具列表所做的、会让 preserved thinking 块失效的改动，逐项量化掉失多少推理，并逐条给出修复、每次改完重新测量v2.1.282+

两点值得单独记。第一，“打一个 / 就能核验当前有哪些内置技能”这句只在技能粒度上成立，在子命令粒度上不成立——/claude-api 在你的版本上能跑哪些子命令，取决于版本号，补全列表看不出来。核验内置技能这件事，从此有了两级：技能级看补全，子命令级看版本号。

第二，preserved-thinking-migration 与第 9 章（上下文与缓存）直接咬合：它量化的正是”哪些改动会打掉 preserved thinking 块”，而且是逐项量化掉失多少推理——这是本书见到的第一个把缓存失效换算成可计量损失、而不是只报”未命中”的官方工具。

清单是快照，内容也是快照。 上面”打一个 / 就能核验”只覆盖有哪些技能；2026-10 末到 11 月初的 changelog 证明技能内容本身也在高频迭代：

  • dataviz 一个月内两次更新（均 v2.1.314）：y 轴刻度标签 <10,000 全显、水平 <1,000,000 全显；donut/pie 请求改为用排序条形图应答——技能的行为准则变了，不只是修 bug。
  • /claude-api 三个版本连续演进：v2.1.309 把 Managed Agents 子代理团队从 coordinator 改建在 multiagent_20261001（dynamic workflows 默认开）；v2.1.314 改为改写前先请求读 workflow run 的 workflow；v2.1.318 给 managed-agents-onboard 的新代理内置工具与快速开始模板 MCP 工具默认配 auto 权限策略（“Judge risky actions”，对齐 Console；说 “run without asking” 可退出）。

结论升级：引用 bundled skill 的具体行为时应同时记录版本号——两个版本之间，/claude-api 给新代理发的默认权限策略可以从「逐项询问」变成「auto」。

源码引用：内置技能定义参见 src/tools/SkillTool/。

12.3 自定义技能

用户可以在两个位置创建自定义技能：

位置路径可见范围
项目级.claude/skills/my-skill/当前项目
用户级~/.claude/skills/my-skill/所有项目

每个技能是一个目录，包含：

.claude/skills/my-skill/
  ├── SKILL.md      # 技能描述和系统提示词（必需）
  ├── scripts/      # 可选的脚本文件
  └── references/   # 可选的参考资料

SKILL.md 定义了技能的身份和行为：

---
name: "my-custom-skill"
description: "一句话描述这个技能做什么"
when_to_use: "当用户要求 X 时使用"
---

<!-- edit: 2026-09-11 原示例用 trigger:，该字段不在官方 20 字段表内，已改为 when_to_use -->

## 系统提示词

你现在要执行以下任务：
1. 先读取项目的 package.json
2. 分析依赖关系
3. 生成依赖报告

## 约束

- 不要修改任何文件
- 输出格式使用 Markdown 表格

当用户调用 /my-custom-skill 时，SKILL.md 中的内容被注入到模型的上下文中——模型根据这些指令执行任务。

完整 frontmatter 字段参考（2026-09-11 官方 code.claude.com/docs/en/skills 快照，共 20 个字段）：

身份与触发

字段说明
name技能列表中显示的名称，缺省取目录名
description（推荐）技能做什么、何时用。Claude 据此判断是否套用该技能；省略时取正文第一个非空行。核心用例要放在最前
when_to_use追加到 description 之后的触发语境，如触发短语或示例请求
argument-hint自动补全时显示的入参提示，如 [issue-number]
arguments命名位置参数，供正文里的 $name 替换；接受空格分隔字符串或 YAML 列表

调用控制

字段说明
disable-model-invocation阻止 Claude 自动加载该技能，只能手动 /name 触发；v2.1.196 起也阻止定时任务携带该技能时触发。默认 false
user-invocable设为 false 时从 / 菜单隐藏，且键入 /name 也不运行——用于只给模型看的背景知识。默认 true
pathsGlob 模式，限定技能仅在操作匹配文件时被自动加载

工具权限

字段说明
allowed-tools调用该技能的那一轮内免询问即可使用的工具，下一轮消息即失效
disallowed-tools技能激活期间从工具池中移除的工具（硬移除），下一轮消息即失效。与 deny 规则一样，在仍有其他工具时不能移除 EndConversation

执行环境

字段说明
context设为 fork 则在子代理上下文中运行
agentcontext: fork 时使用的子代理类型
background仅配合 context: fork。设 false 则等待子代理结果而非后台运行。默认 true，需 v2.1.218+
model技能激活期间使用的模型，仅在当前轮生效、不写入设置。可填 /model 的取值或 inherit。被组织 availableModels allowlist 排除时该值不生效
effort技能激活期间的推理档位，覆盖会话档位。可选 low/medium/high/xhigh/max，档位取决于模型
hooks技能被调用时注册、并在本次会话余下时间持续生效的 Hook
shell技能内 !`command` 与 ```! 块使用的 shell，取 bash（默认）或 powershell

元数据

字段说明
metadata自由 YAML 键值映射，供自有工具读取；Claude Code 不对其内容采取行动，非 map 值会被丢弃。不要复用 paths 等字段名作键
license技能许可证，属 Agent Skills 规范；Claude Code 接受但不据此行动
compatibility环境要求（如适用产品、系统前置条件），属 Agent Skills 规范，最多 500 字符；Claude Code 接受但不据此行动

三条写 SKILL.md 时一定会碰到的规则

  1. 字符预算是具体的 1,536：description 与 when_to_use 的合计文本在技能列表中被截断于 1,536 字符。这给 12.1 的”渐进式披露”提供了量化锚点——不是泛泛的”只加载描述”，而是每个条目 1,536 字符上限。想提高总预算可调 skillListingBudgetFraction（如 0.02 = 2%）或环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET；想压缩单条目，可在 skillOverrides 里把低优先级条目设为 "name-only"，只列名不带描述。

  2. 布尔字段自 v2.1.218 起宽容化：除 true/false 外，接受任意大小写的 yes、no、on、off、1、0。v2.1.218 之前只认 true/false。老写法仍有效。

  3. 没有 trigger 字段：早期版本示例中的 trigger: 不在官方字段表内，应改用 when_to_use（见上）。

  4. allowed-tools 不是绝对权利（v2.1.304）：组织政策只允许插件来源的 hooks 时（12.1 来源治理表的 strictPluginOnlyCustomization 同族），主会话技能的 hooks 被排除，该技能的 allowed-tools 一并失效（官方原文：“a skill used in the main conversation whose hooks are kept out no longer gets its allowed-tools”）。工具授权以 hook 来源资格为前提——技能自带的免询问授权依附于它的 hooks 是否被政策放行。

三个层次的上限（2026-09-29 补，2026-10-19 扩为三个层次，2026-11-06 扩为四个层次）。上面第 1 条说的 1,536 与新增的 skillListingMaxDescChars 是两个不同层次的量，官方把它们放在同一段里，极易被读成同一个数的两次表述：

设置作用层次官方示例取值
skillListingMaxDescChars条目级：每个 skill 在列表里的描述长度上限2048
skillListingBudgetFraction列表级：技能列表可占用的上下文总预算占比0.02（= 2%）
SLASH_COMMAND_TOOL_CHAR_BUDGET列表级：总预算的固定字符数环境变量
子代理预加载（v2.1.295）装载级：子代理从 skills 字段预加载的技能数上限，每个只加载一次32
skill hooks 注册配额（v2.1.304）注册级：每来源（repo / 用户目录 / 插件各计）每会话最多注册的 hooks 数与 matcher 字符数1,024 hooks / 16,384 matcher 字符

新增的第四行与前三行又不是一个量纲：条目级与列表级管列表占多少上下文（字符），装载级管子代理带多少技能（个数），注册级管一个来源能挂多少 hook（个数 + 字符，且三类来源各有独立额度）。它约束的不是技能本身，而是技能通过 hooks 字段注册的 hook——与第 11 章 11.5 的并发上限（v2.1.312：每会话 24 个）是两个正交的量：注册上限管「能挂多少」，并发上限管「同时能跑多少」。

新增的这一行与前三行不是同一件事。前三个量约束的是技能列表占多少上下文——它们是同一个预算在条目级与列表级的两档；32 约束的是子代理启动时带多少技能，量纲是个数而不是字符。所以它是第三个层次，不是同一个旋钮的第三档。带 Skill 工具的子代理仍可调用超出 32 的那部分技能，上限只作用于预加载——这一点决定了它的失效表现是”第一次调用要现取”而不是”用不了”。

官方 skills 文档的原文是”每个条目的合并文本无论预算如何都被截到 1,536 字符，而这个上限现在是可配置的”——也就是说 1,536 是 skillListingMaxDescChars 的默认值，2048 只是文档举的一个调高后的例子。1,536 约束的是 description 加 when_to_use 的合并文本，2048 约束的是同一个位置的长度，二者是同一个旋钮的”默认 / 可调”，不是”条目上限 / 描述上限”两个旋钮。调大预算时的合理顺序是：先动 skillListingMaxDescChars 决定单条目能写多长，再动 skillListingBudgetFraction 或 SLASH_COMMAND_TOOL_CHAR_BUDGET 决定列表总共能吃掉多少上下文；两头不匹配时，先撞上的那头生效。想省预算，skillOverrides 里设为 "name-only" 仍是唯一能完全跳过描述的手段。

Progressive Disclosure Architecture（PDA）：Skill 社区推荐主 SKILL.md 文件控制在 150 行以内，详细的参考资料放在 references/ 子目录中——这确保模型在一次对话中看到的是精炼入口而非知识洪流。官方侧的对应机制是 /skill-doctor（v2.1.252+）：它报告每个技能的成本与被使用频次，交互会话中在 /plugin 管理器的 Stats 标签页打开。

第三个官方测量点：/doctor prompt-audit（v2.1.283）。v2.1.283 新增 /doctor prompt-audit（亦写作 /checkup prompt-audit），审计 CLAUDE.md 文件、技能、agents 与 commands 里为旧模型写的 prompting 模式。覆盖面正好是本章的四类组件：CLAUDE.md（见 Ch09 的上下文预算）、skills（本节）、agents 与 commands（12.1 的插件组件）。把它和已有的两个诊断摆在一起看，官方提供的三个测量点分工是清楚的——/doctor 测 MCP 连通性，/skill-doctor 测技能的成本与用量，/doctor prompt-audit 测写法是否还适配当前模型。前两个回答”能不能用、用了多少”，第三个才回答”写得对不对”。

这条也是本书里少见的官方主动承认”内容会腐烂”的机制：技能是在某个模型代际下写成的，模型换了，当年有效的措辞（过度强调分步、显式要求”仔细思考”之类）可能变成负担。同版本还顺带改进了配置侧的 prompt-audit——陈旧路径、陈旧命令与互相矛盾的指令文件现在排在报告最前面，而 Claude Code 自己文档里记载的 thinking 关键词会被保留。

两个本轮新增的字段相关事实（2026-09-29 补）

  • omitClaudeMd（v2.1.271）：加在 agent frontmatter 与 --agents JSON 上，让自定义与插件子代理在不加载 user / project / local CLAUDE.md 的情况下运行，托管策略文件仍然加载。这是”子代理上下文隔离”唯一的官方开关，与 Ch09 的上下文预算直接咬合：此前想让子代理少看东西，只能靠把它放到没有 CLAUDE.md 的目录里，或者手工收缩 CLAUDE.md 本身——前者不可控，后者会连带影响主会话。注意它的边界是精确的：只豁免 CLAUDE.md，不豁免托管策略，组织下发的行为约束依然生效。
  • effort（v2.1.267 修复）：字段本身早已在表内（见”执行环境”组），本轮补的是它的例外史——v2.1.267 之前，在默认 effort 被钉住的模型（官方点名 Opus 4.7、Opus 4.8、Fable 5）上，自定义命令、技能与子代理的 effort: frontmatter 会被忽略。同一版本还新增了 maxEffortLevel 设置（顶层或 modelSettings 下按模型），用于在包括 Bedrock、Vertex、Foundry 在内的每个 provider 上封顶 effort，用户仍可选更低的档位。

需要说明的是，上面这张 20 字段表统计的是 SKILL.md 的 frontmatter。omitClaudeMd 属于 agent frontmatter，不在该表口径内，因此本轮未把它加进表、也未改动”20 个字段”的计数；这个计数字身是撰写时快照，官方字段表会随版本增删。

同名技能谁生效：按来源判定，不按名称。 12.3 讲了技能放在哪里、谁能看见，但一直没回答”两个技能同名时跑哪个”。官方的答案是按来源判定，而且企业 / 个人 / 项目是三级，不是两级：

同名出现在谁生效
企业、个人、项目中的任意两个企业 > 个人 > 项目。deploy 同时存在于 ~/.claude/skills/ 与项目的 .claude/skills/ 时，/deploy 跑个人的那个
上述任一位置 与 bundled skill你的技能替换该 bundled 命令，但不替换它的别名。项目里的 code-review 替换 /code-review，而 bundled 别名 /review 永远不会去跑你的技能
上述任一位置 与内置命令本地终端会话中你的技能替换内置命令，但不替换其别名。项目里的 usage 替换 /usage，而内置别名 /cost 仍跑内置命令
技能 与 .claude/commands/ 下的文件技能
项目根技能 与 嵌套技能两者都加载（见 monorepo 与子目录的发现规则）
插件技能 与 上述任一位置两者都加载，因为插件技能被命名空间化为 /plugin-name:skill-name
上述任一位置 与 claude.ai 同步技能的短名另一方生效；同步技能随后只在其全名下列出并运行
--add-dir 目录中的技能 与 已有同名技能以 <folder>:<name> 提供而非覆盖（v2.1.309 修复：此前 --add-dir 目录里的同名技能直接不可达）

新补的最后一行是第三种前缀消歧形态：插件技能的 <plugin-name>:、claude.ai 同步技能的 anthropic-skills: 之后，--add-dir 目录撞名现在也走前缀。它强化了本节已有的判据——跨来源汇入同一命名空间的东西，要么加前缀要么接受覆盖不干净；而 --add-dir 此前的行为是第三种也是最差的一种：静默不可达。

反直觉的是第二行与第三行：覆盖了命令本身，却没有覆盖它的别名。这是高频踩坑点——改了半天发现命令没换成自己的，原因可能是自己走的是别名入口（/review、/cost）。这一条与 12.5.4 的命名空间前缀、12.1.1 的 <plugin-name>: 前缀是同一条规则的三个落点：凡是跨来源汇入同一命名空间的东西，要么加前缀区分，要么就得接受”覆盖得不干净”。

技能名安全（v2.1.299 / v2.1.292）。 文件名或目录名含隐藏字符、方向控制字符或类空白字符的技能不再被提供，必须改名；frontmatter 里这样的 name: 被忽略。名字长度上限 256 字符，超出的 name 被忽略（agent 名则是直接拒绝，不是忽略）。

这一条要与第 11 章 11.4 记的那条并列来读：hook matcher 名若撞上 JavaScript 原型链（__proto__、constructor），/hooks 交互菜单会直接崩溃。两者是同一族——都是”用户提供的字符串被当作标识符 / 键使用”这一类实现迟早要补的防御。本书至此已记下三处同源实例（matcher 名、/plugin 与 /skills 的内建属性名、技能名安全），可以抽成一条可复用的规则：凡把用户提供的字符串当名字用的入口，都要防同一类输入——不可见字符、超长、与语言内建标识符相撞。

getSlashCommandToolSkills 函数在启动时扫描项目和用户级的 skills 目录，将发现的技能注册为 Slash 命令。技能的发现是动态的——添加一个新的 SKILL.md 文件后，下次启动 Claude Code 就能看到它。

动态发现有一个曾随工作目录漂移的边界（v2.1.312 修复）。 per-directory 与 paths: 技能，此前在 Bash cd 进入 git 仓库更深层目录后会找不到（“Fixed per-directory and paths: skills not being found after a Bash cd deeper into a git repository”）——目录作用域技能的绑定曾随工作目录漂移失效，修复后按仓库内深层路径可达。依赖 paths: 触发的技能要知道：发现的单位是「当前工作目录可及的范围」，而这个范围在会话中是会动的。

12.4 Skills 的设计精妙之处

Skills 看似简单（只是 Markdown 文件），但它的设计有几个精妙之处：

1. Scripts 目录让技能可以”有手有脚”

scripts/ 目录下的文件可以在技能执行时被引用——技能可以告诉模型”运行 scripts/analyze.py”。这让 Skills 不只是 prompt，而是 prompt + 可执行脚本的组合。

2. References 目录提供知识库

references/ 下的文件被当作技能的参考资料——模型可以在需要时读取它们。这相当于给技能附带了一个微型知识库。

3. 零代码编程

对于不会写 TypeScript 的用户，Skills 提供了一种纯文本方式来扩展 Claude Code 的能力。写一个好的 SKILL.md 本质上是 prompt engineering。

4. Agent 会自己写 skill——从配置物变成产出物

前三条讲的都是人写 skill 给模型用。官方的 /verify 是反向的：当它没有已记录的配方、必须自己摸索如何构建并驱动你的应用时，会把跑通的做法写成 .claude/skills/verify/SKILL.md（仓库根；monorepo 下写在被触碰的包目录），供后续运行与其他 agent 复用。在仓库根时，这个记录下来的技能会替换 bundled 的 /verify。

配套的还有 /run-skill-generator：它从干净环境把应用跑起来，捕获有效做法（安装命令、环境变量、启动脚本），提交为项目级技能 .claude/skills/run-<name>/。三个技能（/run、/verify、/run-skill-generator）构成一组——前两个 infer，第三个 record。官方自己也点明了 infer 的边界：对需要数据库、env 文件、图形会话或多步构建的项目，靠推断”gets unreliable”。

两个设计细节值得抄下来：

  • 写入是有条件的。官方原文：“Claude edits the recorded file only when it steered a run wrong, such as a command that failed or a missing step, so you can commit the file without per-session diffs.” 这是”自动生成的文件能不能进版本库”这个经典问题的答案——只在它把事带偏了才改，所以不会产生每次会话一份噪声 diff。
  • v2.1.286 起它进入提交流程。会话启动时若存在名为 verify 的技能，Claude Code 的提交指令会要求 Claude 在每次提交前运行它（docs 与 tests 的改动除外）。这是本书见到的第一个”技能与官方提交流程挂钩”的机制——技能不再只是被动等待调用。

这条把 12.7 的”Prompt 即代码”推进了一步：skill 不只是代码，还是可以被 Agent 自己产出、并且天然落在 .claude/skills/ 里因而进版本库、可 Code Review 的产出物。同时它也带来一条张力，与下面 12.5.3 的供应链一节直接相连：一个 Agent 自己写的技能，同样要过供应链那一关——它同样会被加载、同样会以你的权限执行，“是我自己的 agent 写的”不构成任何安全论证。

12.5 插件系统

插件比技能更重量级——它们是代码模块，可以定义新的工具、新的命令、新的代理。插件通过 loadAllPluginsCacheOnly 加载，使用缓存机制避免启动时的网络延迟。

插件的动态加载机制有三种策略：

策略触发条件行为
缓存优先SDK/Headless 启动只读本地缓存，不发起网络请求
后台更新运行中在后台异步检查更新
手动刷新/reload-plugins 命令强制清除缓存并重新加载

缓存优先策略确保了 Claude Code 的启动速度不会被插件加载拖慢——即使某个远程插件服务器不可用，也不影响启动。

插件与 Skills 的一个关键区别是权限模型：Skills 继承调用代理的权限，而插件可以定义独立的权限需求——一个插件可以声明”我需要 FileWrite 和 Bash 权限”，用户在启用插件时明确授权。

12.5.2 插件生态现状

插件生态在 2026 年呈现”核心精简、生态填充”的格局，且增长迅猛：

官方目录。Anthropic 维护的 claude-plugins-public 仓库已有 329+ commits（截至 2026 年 5 月），包含两个分区：/plugins（内部开发）和 /external_plugins（第三方提交）。提交需要通过质量和安全审核。

第三方市场。社区驱动的插件市场快速扩张：

市场规模特色
woyin/claude-code-plugins-plus-skills346 插件、4,384+ 技能、16 位贡献者最大社区市场（原 wshobson/agents 后继）
buildwithclaude.com3,687+ 插件插件发现与索引平台
aitmpl.com340 插件 + 1,367 技能插件与技能模板市场
Second Sky Skills Collection v3.3.1170 插件（2026-05-14）精选技能合集

增长趋势。3 个月内 Skill 数量增长约 12 倍（153→1,916），插件生态正从早期的探索阶段进入快速增长期。一个月内插件数从 508 跃升至 3,687（7.3×）——Claude Market 可能扩大了收录标准或吸引了大规模开发者入驻，但需注意 3,687 中”已验证插件”与”全部收录”的区分尚未明确。

独立追踪器技能聚集地：Vercel 推出的 skills.sh 聚合了 876,990+ 全平台 Skills 安装量，标志着 Skills 生态从 Anthropic 官方市场溢出至第三方聚合器——生态独立性正在形成。Skills 不再是 Claude Code 专属资源，而已成为跨平台的 Agent 扩展标准。

这一节到此为止讲的都是”量”，还缺一个维度：这个生态里坏东西的比例是多少。 上面 3,687 插件 / 4,384+ 技能 / 876,990+ 安装量这些数字回答的是”有多大”，而”靠口碑能不能收敛”这个问题要由质量分布来回答。

Snyk 于 2026 年 2 月发布的 ToxicSkills 研究审计了 ClawHub 与 skills.sh 上的 3,984 个技能：36.82%（1,467 个） 至少含一处安全缺陷；13.4%（534 个） 含危重问题（恶意软件分发、凭证窃取）。两个结构性发现比比例本身更有信息量：

  • 已确认恶意的技能 91% 同时使用代码载荷与提示注入——即同时攻击代码执行层与自然语言层，不是二选一；
  • ClawHavoc 活动攻陷 1,184+ 个技能，峰值时下载量前七的技能里有五个是恶意的，向 macOS 用户投递 Atomic Stealer（AMOS）。“前七有五”意味着下载量这个最常用的排序信号在该窗口内是反向指标。

⚠️ 来源标注（2026-10-19 终审升级为一手）：3,984 / 36.82%（1,467）/ 13.4%（534）/ 91% 四个数字本轮回源 Snyk 官方博客原文，逐条命中（扫描时点 2026-02-05，覆盖 ClawHub 与 skills.sh）；ClawHavoc 的 1,184 由 Antiy CERT 口径佐证（跨 12 个发布者账号）。“下载量前七有五”与 AMOS 投递未回源到一手，仍记为二手，两处不参与本节的论证承重。 机制判断（恶意技能同时使用两类载荷）不依赖具体数字，可独立成立。

把这一格放回 12.5 的论证链里就顺了：正因为基数是四位数、坏样本是两位数百分比、且最常用的排序信号在特定窗口内会失效，12.5.3 那四道官方防线才不是可选项。同时它也解释了为什么本章反复强调”来源”这个维度——按来源分级之所以是第一道防线，正是因为按热度排序已经被证明靠不住。

12.5.3 插件运维工具

v2.1.139 新增了多插件场景下的运维工具，解决成本管控问题：

  1. claude plugin details <plugin-name>：显示插件的组件清单和预估每次会话 token 成本——在安装前就能评估插件对上下文的消耗
  2. /context all 精确 token 估算：基于具体模型的分词器计算而非通用近似值，让用户清楚知道每个插件在当前模型下的真实成本
  3. /plugin install @namespace：按命名空间安装插件，自动刷新市场并重试——解决网络抖动导致的安装失败

脚本化运维（v2.1.268，2026-09-10）。上面三条是交互式能力，v2.1.268 补齐了自动化缺口：claude plugin install、uninstall、update、enable、disable 五个子命令全部新增 --json 开关；claude plugin list --json 的每一行新增 errorDetails 与 noteDetails 字段。这意味着插件运维可以真正进 CI——批量安装后能读机器可解析的执行结果，出错时不必去翻人类可读的错误文本。

同期该版本还修了一个与插件相关的安全问题：插件与市场报错时可能把 git 源 URL 中的 token 或密码打印出来（Fixed plugin and marketplace errors showing a token or password from a git source URL）。用 git 源做私有市场的团队应确认自己的版本不低于 v2.1.268。

从”能装能卸”到”装得好不好”（v2.1.269）。上面所有能力都属于生命周期管理——装、卸、更新、查错。v2.1.269 补上了第一个质量验证入口：claude plugin eval，运行插件自带的 eval 套件，产出可打分、可复现的结果（JSON + HTML 报告）。这一步的意义不在命令本身，而在它把插件的评估从”读 README 和看下载量”变成了可回归的工序：JSON 可以进 CI 做阈值断言，HTML 可以给人看细节。至此 12.5 才构成一个闭环——市场发现（12.5.2）、安装运维（12.5.3）、质量验证（eval），缺了任何一环，插件生态都只能靠口碑收敛。

注意 v2.1.283 给它加了一道前置门槛：claude plugin eval 在装有 git 时要求 git 2.31 或更高，更旧的 git 会被拒绝并报出版本号。把 eval 放进 CI 的团队要确认 runner 镜像里的 git 版本。

插件供应链：从一条 bug 修复长成一条线索。12.5.3 里那条 git 凭据泄露修复（v2.1.268）当年是孤立的一个安全问题。到 2026-09-29 这个增量窗口，官方围绕插件已经补出了一条完整的供应链防线，四个环节各司其职：

环节版本官方做法
来源分级v2.1.284 / v2.1.282只有来自官方 Anthropic 源或受管设置为其背书的插件，才能通过 allowed-tools 自我预授权
安装不执行脚本v2.1.275npm 源插件改用 npm pack --ignore-scripts 拉取并做完整性校验，包的安装脚本不再执行
命令级确认v2.1.271claude plugin install / update 新增 --accept-command <sha256>，接受上一次 --json 运行显示的确切命令，取代笼统的 -y
卸载残留v2.1.280修了技能目录里的 manifest.json 会把 ~/.claude/skills/ 下同名技能移入 .trash/ 的问题

其中来源分级最值得单独说，因为它是”插件能给自己发权限”这一设计的实际回撤。v2.1.284 之前，来自 marketplace、claude.ai、npm 的插件都能在托管 allowManagedPermissionRulesOnly 之下通过 allowed-tools 预授权自己的工具；也就是说，组织以为自己用托管策略锁住了权限，装一个社区插件就能把锁打开一道口子。v2.1.284 把这项能力收窄到官方源与受管源，v2.1.282 则补掉了另一半——repository、user、--add-dir 技能与 skills 目录插件 manifest 的同类问题。两次修复合起来才覆盖完全，只升到 v2.1.282 的团队在 marketplace 这条路上仍是敞开的。

回撤在 10 月又扩到第四条路径（v2.1.305）。 Claude Desktop 按路径挂载（by path）的插件，在组织设 allowManagedPermissionRulesOnly 时不再保留 allowed-tools（“Changed plugins that Claude Desktop mounts by path to no longer keep their allowed-tools…”）。四个落点——marketplace（284）、本地目录与技能（282）、Desktop 路径挂载（305）——说明「插件给自己发权限」的回撤是逐路径进行中的过程，不是一次完成的切换；allowManagedPermissionRulesOnly 的覆盖面仍在扩大，引用它的行为时连同版本号一起记。

--accept-command <sha256> 是另一处设计取向的信号：它把”同意执行”从”同意这一次安装”细化到”同意这一个命令”，且凭据是命令内容的哈希而非安装包的版本。配合 v2.1.268 起的 --json，脚本化安装的正确姿势变成先 --json 拿到命令与哈希、人工确认后再用 --accept-command 复现——-y 退化为只适合可信源的快捷方式。

质量闭环的两处漏，都在 2026-10 被补上。 本节把 eval 立为质量验证入口，但入口本身也有失效模式，官方在 v2.1.299 与 v2.1.295 各修了一处：

版本修复为什么重要
v2.1.299claude plugin eval 曾把 API 拒绝的运行判为通过；现在该运行记 0 分、不评分，并让套件 exit 1这是一个假阴性：CI 全绿但插件根本没被测。拿到 exit 1 是可观测的，拿到”通过”不是
v2.1.299eval 新增 --disallow-tools 与 case 字段 disallowed_tools可把 Agent 等内置工具排除在运行之外，测试面从”插件能做什么”收紧到”插件在受限工具集下能做什么”
v2.1.295claude plugin validate 对缺安装行的 README 打印可粘贴的建议行，但明确不改退出码，即使 --strict见下
v2.1.292claude plugin install 新增 --marketplace <name>，先按需加市场并走同样的策略检查，再从它安装合并两条命令的同时没有绕开策略——“先加市场再装”此前是两步，策略检查点容易被跳过

第三条值得单独讲一句，它给出的是一条工程原则：“建议”与”门禁”必须在机制上分开。 plugin validate 发现 README 缺安装行，这件事的性质是”可以更好”，不是”不合格”；如果它改了退出码，CI 就会被一条建议卡死，团队要么放弃 --strict，要么为了过 CI 去写一行没必要的安装说明。一个会卡住流水线的检查，必须只在它真的判定不合格时才卡住。

12.5.5 为什么四道防线都不够：文档即执行

上面四道防线（来源分级、安装不执行脚本、命令级哈希确认、卸载残留）全部是安装期的。它们共同的假设是：危险来自”安装时执行的东西”。DDIPE（arXiv:2604.03081，2026-04-03，Supply-Chain Poisoning Attacks Against LLM Coding Agent Skill Ecosystems）给出的反例恰恰落在这个假设之外。

Document-Driven Implicit Payload Execution 把恶意逻辑藏进技能文档的代码范例与配置模板里。Agent 在正常工作时复现这些范例，载荷随之执行——不需要任何显式指令。论文用 LLM 流水线从 81 个种子生成 1,070 个对抗性技能，覆盖 15 个 MITRE ATT&CK 类别；跨 4 个框架（含 Claude Code）与 5 个模型取得 11.6%–33.5% 的绕过率，而显式指令注入在强防御下为 0%。静态分析能检出多数，但 2.5% 同时逃逸静态检测与模型对齐。责任披露产出四个确认漏洞与两项已部署修复。

这一组数字里最该被记住的是那个反差：显式注入 0%，文档隐式载荷 11.6–33.5%。 它说明对技能这种”看起来只是文档”的载体，对齐防护的方向可能是错位的——模型被训练成拒绝”明确的恶意指令”，但它被训练成照着文档里的范例写代码，而后者正是技能的正常用法。12.3 讲过”SKILL.md 中的内容被注入到模型的上下文中”；DDIPE 说明这件事双向成立：技能不只是”告诉模型怎么做”，它的代码范例还会被模型复现，于是文档即执行。

两条可直接提炼的结论：

  1. 多模型交叉验证是有效层。 论文报告只有 1.6% 的对抗载荷能同时绕过所有被测模型——单个模型会被绕过，但被所有模型同时放过的是极少数。
  2. 但护栏的贡献分布极不均匀。 移除架构护栏后，某一个模型的执行率放大 11.3 倍，而另一个模型完全不变。这意味着不能用”任一模型”来代表护栏的效果，也不能假设在一个模型上验证过就等于在另一个上安全。

静态检测本身也不牢。 另一项工作（arXiv:2607.02357，Cloak and Detonate）用 SkillCloak 做 payload-preserving 变换——保持攻击语义不变、只改外观——在 8 个扫描器与 1,613 个真实恶意技能上测试：SFS Packing（自解压打包，安装期看不见、执行期还原）以 90%+ 的比率绕过每一个扫描器；结构化混淆在多数静态扫描器上绕过 80%+、在混合扫描器上达 96%。作者的结论直白：“appearance-based auditing is insufficient”。论文随后提出的 SkillDetonate 走运行时沙箱 + OS 边界信息流证据，在 97% 检出率下假阳性 2%，在真实恶意技能上仍保持 87%。

所以沙箱执行对技能是必需项，不是可选项。 安装期看外观（来源分级、哈希、静态扫描）拦不住”语义恶意、外观正常”的样本；只有观察它实际做了什么才有解。这一条也解释了为什么 12.5.3 的四道防线是必要的但不充分——它们都是外观层的。

规模旁证：另一项独立研究（arXiv:2602.06547，“Do Not Mention This to the User”: Detecting and Understanding Malicious Agent Skills in the Wild）分析了 98,380 个技能，确认 157 个恶意、632 个含漏洞，横跨 13 种攻击技术。

⚠️ 本小节的 arXiv 数字均已回 abs 页与摘要核对（三篇编号、标题、日期、关键数值一致），但正文表格未逐条回源，4 个框架与 5 个模型的具体名单本书不列。

12.5.4 claude.ai 同步通道

12.5 开头讲的加载三策略（缓存优先 / 后台更新 / 手动刷新）隐含一个前提：技能来自本地目录或本地安装的插件。v2.1.275 起这个前提被打破了——claude.ai 账号上启用的技能与插件会同步到用它登录的终端会话。这条通道同时改了三件事。

源变了。技能不再只来自你或你的组织往磁盘上放的文件，还来自你在网页端勾选的账号配置。v2.1.273 起，登录 Claude 账号会一并请求访问你的 claude.ai 插件；不想同步可分别用 syncClaudeAiSkills: false 与 syncClaudeAiPlugins: false 关掉，两个开关是独立的——只想要账号技能、不想要账号插件是合法配置。

命名空间变了。v2.1.269 起，云端会话里同步来的技能改名为 anthropic-skills:<name>，与 Claude Desktop 对齐；裸名在没有别的东西占用时仍然可用。这是本书反复出现的同一条规则在技能侧的复现——凡是跨来源汇入同一命名空间的东西，迟早要加前缀（12.5.1 里插件技能的 <plugin-name>: 前缀是同因）。

生命周期变了，且带回收。v2.1.273 起，组织关闭 Skills 后，此前同步下来的技能不再继续可用，而是移到可回收的 trash；v2.1.271 起，登出后未在 cleanupPeriodDays 内刷新的本地副本，会在下次启动时同样移入 trash。注意两处措辞都是 trash 而非删除：这是”同步物”区别于”本地安装物”的关键——本地装的插件你显式卸载才消失，同步来的会随账号状态自动降级，且降级是可恢复的。

一个能佐证”这个混淆真实发生过”的细节：v2.1.275 专门改进了 ListPlugins 工具的描述，好让 Claude 知道它列的是账号上启用的插件，而不是用 /plugin 本地安装的那些。官方会去改一个工具描述来纠正误解，说明误解已经造成过实际后果。读者在排查”我明明装了却看不到”或”我没装却出现了”这类问题时，第一件事应该是分清这两个来源。

时效也变了，而且这个数字刚被改过一次。 上面三条（源、命名空间、生命周期）都缺了运维上最实际的一问：网页端改了，终端多久能看到。v2.1.293 起，在没有会话使用时的同步检查间隔从约每 10 分钟放宽到约每 40 分钟。同一版本还修了一个相邻问题：claude.ai 同步技能在网页端改了描述之后，有时要到新会话或 /clear 才生效。

按本章体例，这个数字要连同快照一起记：40 分钟是 2026-10 的取值，且它本身在本月刚从 10 分钟改过来——正属于”凡是会变的默认值，记快照 + 记它会变”那一类。实践含义很直接：网页端勾完技能立刻到终端里找，找不到不一定是同步坏了，很可能只是还没到 40 分钟的轮询点；要立刻生效就开新会话或 /clear。

同步检查有机器级缓存，trash 也有了边界。 两条 2026-11 的补充把源、命名空间、生命周期、时效这四条之外的两块运维面积补齐了：

  • 同机复用（v2.1.311）：设了 CLAUDE_CODE_SYNC_SKILLS 且 feature-flag 拉取关闭的会话，可复用同一台机器上另一个会话 10 分钟内取过的 skills list——同步检查从「每会话各自拉」变成了「机器级共享缓存」。
  • trash 有界（v2.1.314）：~/.claude/skills/.trash 与 ~/.claude/plugins/.trash 此前无限增长，现在各持有约 1,024 条，且与 cleanupPeriodDays 解耦（“whatever cleanupPeriodDays says”）；文件监视器也不再盯着 trash 里每个已删技能（此前其负载随删除数增长）。trash 从「可回收」补上了「有界」——生命周期那条里”降级是可恢复的”现在有了存储侧的硬顶。

⚠️ 与 12.5.2 生态数据的关系：本节讨论的是同步机制，不改变 12.5.2 的市场规模统计口径——那些数字统计的是各市场的收录量，与单个用户账号上启用了多少是两回事。

12.5.1 plugin.json 参考架构

插件的 plugin.json 清单定义了插件的元数据和行为规范：

字段类型说明依据
namestring插件唯一标识符，同时决定插件技能的命名空间前缀（如 /my-plugin:hello）官方
versionstring语义化版本（如 1.0.0）官方
descriptionstring插件功能描述官方
installationScope ⚠️string安装范围（global/user/project）仅见第三方文档
environmentVariables ⚠️object运行时环境变量配置仅见第三方文档

⚠️ installationScope 与 environmentVariables 存疑：这两个字段在官方 code.claude.com/docs/en/plugins 与 settings-reference 两页中零命中，官方 plugin.json manifest 只明示 name、description、version 三项（以及可通过 settings 键声明设置，其优先级低于插件根的 settings.json）。本表保留原内容是因为它来自第三方整理，但读者不应依赖这两个字段——挂在表里的来源是真的，不代表字段本身有官方依据（这与本书反复出现的”引用真 ≠ 数据安全”是同一类问题）。

官方给出的关键约束是命名空间：插件技能一律带 <plugin-name>: 前缀以避免同名冲突，改 plugin.json 的 name 即改前缀。

第三个已确认的声明维度：MCP servers（2026-09-29 补）。上表说官方只明示 name / version / description 三项加 settings 键，这个判断在 2026-09-11 是成立的，但漏了一类：插件可以在 plugin.json 里声明 MCP 服务器。证据不是文档，而是一个 bug 修复——v2.1.283 修的是 claude plugin details 对”在 plugin.json 里声明服务器的插件显示 0 个服务器”。官方修计数为 0 这个现象，反证声明本身是被支持的；如果 plugin.json 不接受 MCP servers，正确的修复会是报”未知字段”而不是补计数。

这把 12.1.1 目录树里的 .mcp.json 与 plugin.json 的关系讲清楚了：.mcp.json 是按约定扫描的服务器配置文件，而 plugin.json 里的声明是显式登记。两者并存时，plugin.json 走的是与”设置 manifest 键取代目录扫描”一致的偏好。

配套的是 v2.1.281 起 claude plugin validate 新增的 MCP 服务器检查，它对 .mcp.json 报告三类问题：加载时会被静默丢弃的条目、未声明的 ${user_config.*} 引用、不安全的 URL。第一类最阴——配置写错了不报错，只是不生效，与 Ch10 记过的”连上了但状态不可信”是同一类失败态。第三类则把 URL 安全性从事后审计提到了安装前校验。

编辑说明：上表原基于 lobehub 发布的完整插件参考文档（2026年1月）。该文档详细记录了 plugin.json Schema、目录布局、bundle 方式、CLI 打包安装命令、验证缓存行为、版本分发和企业部署特性。其中目录布局部分已被本轮按官方原文重画（见 12.1.1）。

12.6 Skills 与 Plugins 的协同

Skills 和 Plugins 不是互相替代的——它们在生态中协同工作：

复杂度递增 →

  Hooks          Skills          Plugins
  ↑              ↑               ↑
  工具级扩展     提示词级扩展     代码级扩展
  简单脚本       Markdown 文件    TypeScript 模块
  被动触发       主动调用         自动集成
                        ↑
                  Plugins 打包 Skills
                  （插件是技能的分发格式）

一个典型的扩展路径：先用 Hook 做简单的前后处理，发现 prompt 模板有价值后升级为 Skill，如果需要自定义工具逻辑再开发 Plugin。如果想把 Skill 分享给其他用户，可以将其打包为 Plugin 发布到插件市场。

编辑说明：Plugins 打包 Skills 的生态关系基于 agensi.io 2026 年文章补充。

12.7 设计启示

  1. “Prompt 即代码”是一种有效的扩展模式。Skills 证明了很多扩展不需要写代码——一个精心设计的 prompt 模板就够了。

  2. 两层扩展降低了入门门槛。不是所有用户都会写 TypeScript，但几乎所有开发者都能写 Markdown。

  3. 缓存优先的加载策略是 CLI 工具的生命线——用户不会容忍一个因为加载远程插件而卡 10 秒的工具。

  4. “协议→模块→分发”的三层标准化路径。从行业视角看，Anthropic 的扩展体系走了一条教科书级的标准化路径：MCP（2024 年末）将 AI 与工具/数据连接标准化，已获 OpenAI 采纳；Agent Skills（2025-10）定义可被任何 AI 平台加载的能力模块格式；Plugin Marketplace（2026-04）建立社区自增长的打包分发渠道。每一步都将扩展能力从”Anthropic 专有”下沉为”行业标准”——对比 Cursor 选择抢占编辑器位置、Codex 赌云端异步的不同策略，这三种路径折射出 AI 编程工具生态位竞争的深层逻辑。