生态扩展总览

1. 定位

从源码结构看，Claude Code 的“生态扩展”并不是一个单点模块，而是三套相互配合的扩展机制：

src/skills/：把提示能力、命令能力和少量运行时约束封装成可调度的 Skill。
src/utils/plugins/：负责插件的发现、安装、缓存、校验、装配与失效刷新。
src/services/mcp/：负责把外部 MCP 服务接入为系统内的 tools、commands、resources 与连接状态。

如果只看目录名，容易把三者理解成并列功能；但从运行链路看，它们更像分层架构：

Skill 是提示与命令层扩展。
Plugin 是本地分发、组件注入与能力装配层。
MCP 是运行时协议接入层。

也就是说，系统并不是“先有一个核心，再给它外挂几个补丁”，而是从设计上就允许多种能力来源进入统一会话。

2. 总装配链路

生态扩展的装配顺序，大致可以抽象为下面这条链路：

main.tsx
  -> 初始化 built-in plugins / bundled skills
  -> getCommands() 汇总 bundled、本地、plugin、workflow 等命令
  -> pluginLoader 加载 marketplace / inline / builtin plugins
  -> MCP config 汇总 user / project / local / plugin / claude.ai 等 server 配置
  -> MCP client 建连并拉取 tools / prompts / resources / skills
  -> 会话运行时统一消费这些能力

从 src/main.tsx 可以看到，initBuiltinPlugins() 与 initBundledSkills() 会在启动早期执行，目的是让 getCommands() 在首次汇总命令时就能读到这些内存态扩展，而不是等到后续异步流程结束后再补注册。

再往后，src/commands.ts 会把多类来源统一折叠为 Command[]：

bundled skills
内置插件导出的 skill commands
磁盘目录中的 skills
plugin commands / plugin skills
builtin commands

这一步已经说明，Skill 并不是孤立于命令系统之外的“附属提示词”，而是命令汇总阶段的一等公民。

3. 三套机制的职责分层

3.1 Skill：提示与命令层

Skill 的核心目标是把一段能力描述、一组 frontmatter 元数据和可选的运行约束，转成可被模型或用户触发的 Command。它关注的是：

如何定义能力
如何声明工具权限与适用场景
如何进入命令体系

它更像“能力说明书 + 调度入口”。

3.2 Plugin：分发与装配层

Plugin 系统不直接等价于某一种能力，而是负责把多种组件打包、安装并送进运行时。一个插件既可以提供 commands，也可以提供 skills、hooks、output styles、settings、LSP servers，或者继续提供 MCP servers。

因此 Plugin 更像“本地生态分发容器”。

3.3 MCP：协议接入层

MCP 集成负责对接外部服务。它既处理配置聚合，也处理 transport、auth、session 与 tool call 的真实执行。进入系统后，这些远端能力会被重新包装为：

MCP tools
MCP prompts / commands
MCP skills
MCP resources

因此 MCP 更像“把外部能力接成内部能力总线”的协议层。

4. 三者之间的耦合关系

这三层并不是单向串联，而是存在几个关键耦合点。

4.1 Plugin 可以向下提供 Skill 与 MCP

插件 manifest 与 marketplace entry 不只声明元信息，也可以声明：

commands
agents
skills
hooks
outputStyles
settings
mcpServers
lspServers

这意味着 Plugin 是向 Skill 系统和 MCP 系统输送能力的上游。

4.2 MCP 不只提供 tools，也会回流到 commands / skills

从 src/services/mcp/client.ts 与 src/services/mcp/useManageMCPConnections.ts 可以看到，MCP 客户端在建连后并不只拉取 tools，也会拉取 prompts、resources，以及 feature 打开时的 MCP skills。src/commands.ts 里还专门有 getMcpSkillCommands()，用于把 loadedFrom === 'mcp' 的命令筛出来并并入 skill 视图。

这说明 MCP 是“运行时接入层”，但它的结果会直接影响命令层和技能层的可见能力集合。

4.3 Skill 解析逻辑被 MCP 复用

src/skills/mcpSkillBuilders.ts 的存在很关键。它把 loadSkillsDir.ts 里的 createSkillCommand() 与 parseSkillFrontmatterFields() 以注册表方式暴露出来，供 MCP skill 发现逻辑复用，同时避免 client.ts -> mcpSkills -> loadSkillsDir.ts 形成循环依赖。

这意味着系统并没有为“本地 skill”和“MCP skill”维护两套独立建模逻辑，而是在命令对象构造层尽量统一。

5. 生态扩展的统一落点

无论能力来自本地目录、插件、还是远程 MCP 服务，最终都要进入同一套运行时对象：

Command
Tool
ServerResource
MCPServerConnection

也正因为落点统一，Claude Code 才能在同一轮会话里把内建工具、插件组件、Skill 和远端协议能力一起交给模型使用。

所以，“生态扩展”这一章最重要的结论不是三套机制各自做了什么，而是它们如何共同构成一个统一的能力接入面：

Skill 负责定义和暴露能力。
Plugin 负责分发和装配能力。
MCP 负责接入和执行外部能力。

下面三个小节分别拆开分析它们的内部机制。

Claude Code Harness Engineering Notes