章节导航第 12 章 / 共 23 章

第 12 章第四部分：工程细节

Skills 与插件体系

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

最后更新：2026年9月29日 Claude Code Skills 插件扩展机制 SkillTool

12.1 两层扩展架构

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

维度	Skills	Plugins
本质	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 是传统的代码扩展。

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 起才真正挡得住。

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

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

12.2 内置技能

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

类别	技能（内部标识）	功能	触发条件	对外斜杠命令
配置管理	updateConfig	修改 settings.json	用户想更改设置	未作为 bundled skill 收录
	keybindings	自定义快捷键配置	用户想改键位	未作为 bundled skill 收录
API 指导	guideClaudeApi	Claude API 使用指导	用户问 API 用法	`/claude-api`
代码操作	verifyCode	代码验证	需要检查代码正确性	`/verify`
	debugCode	调试辅助	排查 Bug	`/debug`
项目管理	createPlan	创建分步实施计划	复杂任务需要规划	未作为 bundled skill 收录
	reviewPR	PR 审查	代码审查场景	`/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。

源码引用：内置技能定义参见 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
paths Glob 模式，限定技能仅在操作匹配文件时被自动加载

工具权限

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

执行环境

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

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

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

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

设置作用层次官方示例取值
skillListingMaxDescChars 条目级：每个 skill 在列表里的描述长度上限 2048
skillListingBudgetFraction 列表级：技能列表可占用的上下文总预算占比 0.02（= 2%）
SLASH_COMMAND_TOOL_CHAR_BUDGET 列表级：总预算的固定字符数环境变量

官方 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 个字段”的计数；这个计数字身是撰写时快照，官方字段表会随版本增删。

字段	说明
`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`
`paths`	Glob 模式，限定技能仅在操作匹配文件时被自动加载

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

字段	说明
`context`	设为 `fork` 则在子代理上下文中运行
`agent`	`context: 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 接受但不据此行动

设置	作用层次	官方示例取值
`skillListingMaxDescChars`	条目级：每个 skill 在列表里的描述长度上限	`2048`
`skillListingBudgetFraction`	列表级：技能列表可占用的上下文总预算占比	`0.02`（= 2%）
`SLASH_COMMAND_TOOL_CHAR_BUDGET`	列表级：总预算的固定字符数	环境变量

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

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。

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-skills	346 插件、4,384+ 技能、16 位贡献者	最大社区市场（原 wshobson/agents 后继）
buildwithclaude.com	3,687+ 插件	插件发现与索引平台
aitmpl.com	340 插件 + 1,367 技能	插件与技能模板市场
Second Sky Skills Collection v3.3.1	170 插件（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 扩展标准。

12.5.3 插件运维工具

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

claude plugin details <plugin-name>：显示插件的组件清单和预估每次会话 token 成本——在安装前就能评估插件对上下文的消耗
/context all 精确 token 估算：基于具体模型的分词器计算而非通用近似值，让用户清楚知道每个插件在当前模型下的真实成本
/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.275	npm 源插件改用 `npm pack --ignore-scripts` 拉取并做完整性校验，包的安装脚本不再执行
命令级确认	v2.1.271	`claude 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 这条路上仍是敞开的。

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

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 本地安装的那些。官方会去改一个工具描述来纠正误解，说明误解已经造成过实际后果。读者在排查”我明明装了却看不到”或”我没装却出现了”这类问题时，第一件事应该是分清这两个来源。

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

12.5.1 plugin.json 参考架构

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

字段	类型	说明	依据
`name`	string	插件唯一标识符，同时决定插件技能的命名空间前缀（如 `/my-plugin:hello`）	官方
`version`	string	语义化版本（如 1.0.0）	官方
`description`	string	插件功能描述	官方
`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 设计启示

“Prompt 即代码”是一种有效的扩展模式。Skills 证明了很多扩展不需要写代码——一个精心设计的 prompt 模板就够了。
两层扩展降低了入门门槛。不是所有用户都会写 TypeScript，但几乎所有开发者都能写 Markdown。
缓存优先的加载策略是 CLI 工具的生命线——用户不会容忍一个因为加载远程插件而卡 10 秒的工具。
“协议→模块→分发”的三层标准化路径。从行业视角看，Anthropic 的扩展体系走了一条教科书级的标准化路径：MCP（2024 年末）将 AI 与工具/数据连接标准化，已获 OpenAI 采纳；Agent Skills（2025-10）定义可被任何 AI 平台加载的能力模块格式；Plugin Marketplace（2026-04）建立社区自增长的打包分发渠道。每一步都将扩展能力从”Anthropic 专有”下沉为”行业标准”——对比 Cursor 选择抢占编辑器位置、Codex 赌云端异步的不同策略，这三种路径折射出 AI 编程工具生态位竞争的深层逻辑。