从 Skill 说起很多人第一次接触 Claude Code 的 Skill会把它理解为一个放在.claude/skills/目录下的 Markdown 文件。这种理解不能说错但只看到了最表面的一层。在 Claude Code 当前的扩展体系中Skill 并不是最高层级的分发单元。一个完整的能力包还可能包含SkillsSlash CommandsSubagentsHooksMCP ServerLSP ServerSettings可执行脚本和参考资料这些内容通常会被封装成一个Plugin再由Marketplace负责发现、分发和安装。因此Claude Code 的扩展体系更接近Marketplace ↓ Plugin ├── Skill ├── Command ├── Agent ├── Hook ├── MCP Server └── 其他运行时配置 ↓ Claude Code Harness如果想理解 Claude Code 的 Marketplace 与 Skill就不能只研究SKILL.md而要先看清这三个层级Marketplace能力目录和分发源 Plugin安装、启用和版本管理的能力包 SkillPlugin 内部的一种可复用任务能力本文先从文件系统和配置文件入手建立 Claude Code 扩展体系的完整静态结构。一、Claude Code 的整体目录地图1、Claude Code 的能力扩展体系不是单层目录Claude Code 中的能力可能来自多个位置Claude Code 内置能力 用户目录 ~/.claude/ 项目目录 .claude/ 已安装 Plugin来自 Claude 官方 或者 第三方 Marketplace 组织托管配置 当前会话参数这些来源最终都会被 Claude Code Harness 汇总成当前会话可用的能力集合。可以先建立一个简化模型┌─────────────────────────────────────┐ │ Claude Code 内置能力 │ │ Read / Write / Edit / Bash / Agent │ └──────────────────┬──────────────────┘ │ ┌──────────────────▼──────────────────┐ │ 用户级配置 ~/.claude/ │ │ Skills / Agents / Commands / Settings│ └──────────────────┬──────────────────┘ │ ┌──────────────────▼──────────────────┐ │ 项目级配置 project/.claude/ │ │ Skills / Agents / Rules / Settings │ └──────────────────┬──────────────────┘ │ ┌──────────────────▼──────────────────┐ │ Plugin Registry │ │ Marketplace 安装的 Plugin │ └──────────────────┬──────────────────┘ │ ┌──────────────────▼──────────────────┐ │ Managed Settings │ │ 企业策略、白名单和强制插件 │ └──────────────────┬──────────────────┘ ▼ Claude Code Runtime这里有一个非常重要的区别.claude/skills/适合直接放置项目或用户维护的 SkillMarketplace 更适合分发结构完整、具有版本和来源信息的 Plugin。2、Claude Code 的各个能力位置的具体结构Claude Code 没有要求用户理解所有内部目录但从系统角度看可以把相关文件分为四组1. 项目级配置 2. 用户级配置 3. 企业级托管配置 4. Marketplace 与 Plugin 数据一个比较完整的逻辑结构如下project/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── settings.local.json │ ├── skills/ │ │ └── code-review/ │ │ ├── SKILL.md │ │ ├── references/ │ │ ├── scripts/ │ │ └── assets/ │ ├── agents/ │ │ └── reviewer.md │ ├── commands/ │ │ └── review.md │ └── rules/ │ ├── .mcp.json ├── src/ └── tests/用户级配置通常位于~/.claude/ ├── CLAUDE.md ├── settings.json ├── skills/ ├── agents/ ├── commands/ ├── projects/ └── plugins/marketplaces (Marketplace 与 Plugin 数据)企业环境还会存在托管配置文件。官方当前列出的典型位置包括macOS /Library/Application Support/ClaudeCode/managed-settings.json Linux / WSL /etc/claude-code/managed-settings.json Windows C:\Program Files\ClaudeCode\managed-settings.json托管配置拥有最高级别的策略控制能力例如限制用户可以添加哪些 Marketplace。需要注意的是Claude Code 的部分内部缓存和状态文件并不是稳定公共 API。文章后续提到这类目录时应区分公开配置规范 → 可以依赖和版本控制 内部状态与缓存 → 可以观察但不应该作为稳定接口依赖3、各个能力位置中的几个最重要的配置文件1.CLAUDE.mdCLAUDE.md是 Claude Code 的长期上下文文件。它通常用于描述项目架构 编码规范 构建命令 测试方式 依赖选择 禁止事项 提交要求 团队约定例如# Project Instructions ## Architecture This is a Spring Boot WebFlux project. ## Commands - Build: mvn clean package - Test: mvn test - Run: mvn spring-boot:run ## Rules - Do not introduce Spring MVC dependencies. - Use Reactor types for asynchronous APIs. - Add tests for all public service methods.CLAUDE.md不是 Skill也不是 Plugin。它解决的是Claude 在这个项目中应该遵守哪些长期规则Skill 解决的则是Claude 应该怎样完成某一类任务二者的关系可以理解为CLAUDE.md → 项目全局约束 SKILL.md → 特定任务的方法与流程2..claude/settings.json这是项目级 Claude Code 配置。它适合进入版本控制由团队成员共同使用。内容可能包括权限规则 Hook 配置 Plugin 启用状态 环境设置 工具限制 Marketplace 或组织扩展配置示意结构{permissions:{allow:[Bash(mvn test:*),Bash(git diff:*)],deny:[Bash(rm -rf:*)]}}这里的权限不是 Skill 自己的执行权限而是 Claude Code Harness 对工具调用的统一约束。即使某个 Skill 指示 Claude 执行一条命令最后仍然要经过 Claude Code 的权限系统。3..claude/settings.local.json这是当前开发者在当前项目中的本地配置。通常不应提交到版本控制。它适合存放个人权限偏好 本机路径 本地调试配置 只对当前开发者生效的插件状态 临时 Hook可以把两个文件理解为settings.json → 团队共享配置 settings.local.json → 当前开发者的本地覆盖配置4..mcp.json.mcp.json用于声明项目级 MCP Server。示例{mcpServers:{project-database:{type:stdio,command:node,args:[./tools/database-mcp.js]}}}MCP 与 Skill 的关系非常重要MCP Server → 提供工具能力 Skill → 指导 Claude 如何组合这些工具例如PostgreSQL MCP → query_database 工具 database-migration Skill → 数据库迁移的检查、执行和验证流程Claude Code 的 Plugin 也可以携带.mcp.json让插件安装后获得外部工具能力。官方插件仓库给出的标准 Plugin 目录中就把.mcp.json列为可选文件。二、Claude Code 的 Marketplace1、Marketplace 在 Claude Code 中到底是什么Claude Code 的 Marketplace 在 ~/.claude/plugins/marketplaces/ 中 并不只是一个网页。从文件结构上看它更接近一个包含.claude-plugin/marketplace.json的 Git 仓库或本地目录。典型 Marketplace 仓库my-marketplace/ ├── .claude-plugin/ │ └── marketplace.json ├── plugins/ │ ├── code-review/ │ ├── release-manager/ │ └── frontend-design/ ├── external_plugins/ └── README.md其中最关键的文件就是.claude-plugin/marketplace.json它不是某个 Plugin 的配置而是整个 Marketplace 的插件目录插件地图。可以把它理解为Marketplace Catalog其中记录Marketplace 名称 Marketplace 描述 维护者信息 Plugin 列表 每个 Plugin 的来源 分类 主页 版本或 Commit 重命名映射2、marketplace.json的核心结构Claude Code 官方 Marketplace 当前使用的文件位置是.claude-plugin/marketplace.json官方仓库中的顶层结构包括{$schema:https://anthropic.com/claude-code/marketplace.schema.json,name:claude-plugins-official,description:Directory of popular Claude Code extensions,owner:{name:Anthropic,email:supportanthropic.com},renames:{},plugins:[]}官方 Marketplace 当前确实使用了name、description、owner、renames和plugins等字段。1.$schema{$schema:https://anthropic.com/claude-code/marketplace.schema.json}它用于编辑器字段提示JSON 校验Marketplace 结构验证CI 中的格式检查。但需要注意Schema URL 是规范入口不代表 Claude Code 安装时只依赖在线 Schema。Claude Code 自身仍需要内置对应的解析和校验逻辑。2.name{name:claude-plugins-official}Marketplace 名称非常重要因为 Plugin 的完整安装标识通常是plugin-namemarketplace-name例如code-reviewclaude-plugins-official这说明 Claude Code 使用 Marketplace 名称作为命名空间的一部分。仅仅知道 Plugin 名称并不总是足够因为不同 Marketplace 中可能存在同名 Plugin。3.owner{owner:{name:Anthropic,email:supportanthropic.com}}owner描述的是 Marketplace 维护者而不一定是其中所有 Plugin 的作者。因此需要区分Marketplace Owner → 管理整个插件目录 Plugin Author → 开发某一个具体插件一个企业可以维护内部 Marketplace其中包含多个团队开发的 Plugin。4.renames官方 Marketplace 当前还包含renames{renames:{old-plugin-name:new-plugin-name}}这个字段用于处理 Plugin 重命名。它说明 Marketplace 不只是静态列表还承担了部分演进和兼容职责。例如用户原来安装 old-pluginmarketplace Marketplace 更新后 old-plugin → new-plugin如果没有重命名映射Plugin 改名可能导致已安装状态失联更新失败用户需要手动卸载重装项目配置继续引用旧名称。5.plugins这是 Marketplace 的核心。一个简单的 Plugin Entry 可能是{name:code-review,description:Automated code review for pull requests,author:{name:Anthropic},source:./plugins/code-review,category:productivity,homepage:https://github.com/example/code-review}官方 Marketplace 中的code-review就使用了相对目录作为 Source。这种方式表示Marketplace 仓库 └── plugins/ └── code-review/即 Plugin 内容与 Marketplace Catalog 位于同一个仓库中。3、Plugin Source 的几种形态Claude Code Marketplace 的一个重要设计是 Plugin 不一定必须与 Marketplace 位于同一个仓库。从当前官方 Marketplace 可以观察到几种 Source 形式。1. 相对目录{source:./plugins/code-review}适合单仓库 Marketplace 企业内部插件仓库 官方维护的插件集合优点是结构简单Marketplace 和 Plugin 可以一起版本管理。缺点是 Marketplace 仓库可能越来越大。2. 独立 Git URL{source:{source:url,url:https://github.com/example/plugin.git,sha:...}}官方 Marketplace 中已经存在这种形式并使用sha固定具体 Commit。它适合Plugin 独立维护 Marketplace 只维护索引 第三方厂商发布自己的插件仓库这种模式下Marketplace → 只提供目录和可信入口 Plugin Repository → 独立维护代码和版本3. Git 仓库子目录{source:{source:git-subdir,url:https://github.com/example/plugins.git,path:plugins/security-review,ref:v1.5.5,sha:...}}官方 Marketplace 当前也使用了git-subdir、path、ref和sha组合。这种模式适合 Monorepocompany-agent-plugins/ ├── plugins/ │ ├── java-review/ │ ├── database/ │ └── release/ └── shared/Marketplace 可以只安装其中一个子目录而不必把整个仓库都当成一个 Plugin。4、Marketplace 更接近“Git Catalog”而不是传统应用商店从marketplace.json的设计可以看出Claude Code Marketplace 当前更接近Homebrew Tap Git Plugin Catalog Package Source Index而不是传统意义上的App Store VS Code Marketplace Chrome Web Store原因在于它的核心结构是Marketplace Git Source ↓ marketplace.json ↓ Plugin Source ↓ Plugin Repository 或目录Marketplace 主要解决Plugin 从哪里发现 Plugin 的名称和描述 Plugin 的代码在哪里 Plugin 属于什么分类 Plugin 对应哪个版本或 Commit而评论、付费、复杂推荐、下载统计等传统商店功能并不是本地 Marketplace 文件的核心职责。5、官方 Marketplace 的仓库分为内部开发和维护和第三方提供Anthropic 当前维护了官方 Plugin Marketplace其仓库结构明确区分plugins/ → Anthropic 内部开发和维护的 Plugin external_plugins/ → 合作伙伴和社区提供的第三方 Plugin官方仓库文档也明确说明了这一分类。整体结构可以抽象为claude-plugins-official/ ├── .claude-plugin/ │ └── marketplace.json ├── plugins/ │ ├── code-review/ │ ├── commit-commands/ │ ├── plugin-dev/ │ └── skill-creator/ ├── external_plugins/ │ ├── playwright/ │ ├── serena/ │ └── ... └── README.md但并非marketplace.json中的所有 Plugin 都必须真实存在于这两个目录。一些 Plugin Entry 会引用外部 Git 仓库。所以更准确的理解是官方 Marketplace Catalog ├── 官方仓库内置 Plugin ├── 官方仓库中的外部 Plugin 镜像或目录 └── 指向第三方独立仓库的 Plugin Entry三、Claude Code 的 Plugin1、Plugin 的标准目录结构一个 Plugin 的核心结构如下plugin-name/ ├── .claude-plugin/ │ └── plugin.json ├── .mcp.json ├── commands/ ├── agents/ ├── skills/ └── README.md这是 Anthropic 官方 Plugin 仓库给出的标准结构。更完整的 Plugin 还可能包含plugin-name/ ├── .claude-plugin/ │ └── plugin.json │ ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── references/ │ │ ├── scripts/ │ │ └── assets/ │ └── security-review/ │ └── SKILL.md │ ├── commands/ │ ├── review.md │ └── review-pr.md │ ├── agents/ │ ├── code-reviewer.md │ └── security-reviewer.md │ ├── hooks/ │ └── hooks.json │ ├── .mcp.json ├── scripts/ ├── README.md └── LICENSE这说明一个 Plugin 可以是一组相互配合的能力而不只是一个 Skill。2、plugin.json的角色每个标准 Plugin 都需要.claude-plugin/plugin.json它是 Plugin Manifest。其作用类似package.json pom.xml plugin.yaml extension.json一个简化示例{name:code-review,version:1.0.0,description:Automated code review workflows,author:{name:Example Team}}需要特别注意marketplace.json → 描述 Marketplace 中有哪些 Plugin plugin.json → 描述当前目录本身是什么 Plugin两者职责不同。可以类比 Mavenmarketplace.json ≈ Repository Index plugin.json ≈ 单个 Artifact 的 Manifest3、Marketplace Entry 与plugin.json为什么会重复你可能会发现marketplace.json 中有 name、description、author、version plugin.json 中也有 name、description、author、version这并不是完全重复而是两个阶段的数据。Marketplace 阶段在 Plugin 尚未安装时Claude Code 需要展示Plugin 名称 简介 作者 分类 来源 主页因此这些字段必须出现在marketplace.json中否则用户还没有下载 Plugin就无法浏览其信息。Plugin 运行阶段Plugin 安装以后Claude Code 需要从本地目录识别这是什么 Plugin 版本是多少 有哪些元信息 是否符合 Plugin 结构因此 Plugin 自身还需要plugin.json。可以理解为Marketplace Entry → 安装前元数据 plugin.json → 安装后本地 Manifest这两个文件之间理论上应该保持一致但也存在漂移风险Marketplace 声明版本 1.2 Plugin Manifest 声明版本 1.1后续研究需要重点确认 Claude Code 遇到不一致时以哪个为准以及是否执行一致性校验。4、Plugin 内各组件分别是什么1. Skillskills/ └── code-review/ └── SKILL.mdSkill 用于描述适用场景 执行方法 工作流程 参考知识 工具组合 验证方式 输出格式它主要是程序性知识和任务方法。2. Commandcommands/ └── review.mdCommand 提供用户显式调用入口例如/code-review:reviewPlugin 中的能力通常带有命名空间GitHub Actions 官方文档也使用/plugin-name:skill-name来调用 Plugin 中的 Skill。命名空间可以避免不同 Plugin 都定义 /review导致的冲突。3. Agentagents/ └── code-reviewer.mdAgent 是一个专用 Subagent 定义。它拥有独立角色 独立提示词 独立上下文 可配置的工具集合Plugin Agent 安装后会自动与用户自定义 Agent 一起加载并以带作用域的名称出现在 Agent 选择中。但出于安全考虑Plugin 中的 Agent 不能通过 Frontmatter 自行启用hooks、mcpServers或permissionMode。这些字段在 Plugin Agent 中会被忽略。这说明 Claude Code 对 Plugin 能力并非完全无条件信任。4. HookHook 用于在生命周期事件发生时执行动作。例如文件编辑后自动格式化 执行命令前检查 任务结束后运行测试 提交前运行 LintHook 与 Skill 最大区别是Skill → 模型判断和遵循 Hook → 事件触发Hook 更确定也更危险因为它可能在事件发生时直接执行 Shell 或 HTTP 请求。5. MCP ServerPlugin 根目录可以包含.mcp.json它用于给 Plugin 提供真正的外部工具例如GitHub API 数据库 浏览器 监控平台 云服务 内部业务系统因此一个完整 Plugin 可以形成MCP → 提供工具 Skill → 提供使用方法 Command → 提供用户入口 Agent → 提供独立执行者 Hook → 提供生命周期自动化5、一个完整 Plugin 的逻辑结构以代码审查 Plugin 为例code-review-plugin/ ├── .claude-plugin/ │ └── plugin.json │ ├── skills/ │ └── review-code/ │ ├── SKILL.md │ └── references/ │ ├── security.md │ └── java-style.md │ ├── commands/ │ └── review.md │ ├── agents/ │ ├── correctness-reviewer.md │ ├── security-reviewer.md │ └── maintainability-reviewer.md │ ├── hooks/ │ └── hooks.json │ └── README.md它的执行关系可能是用户执行 /code-review:review ↓ Command 加载代码审查任务说明 ↓ Claude 读取 review-code Skill ↓ Skill 要求 1. 获取 Diff 2. 识别改动模块 3. 并行启动审查 Agent 4. 合并结论 5. 按置信度过滤 ↓ correctness-reviewer security-reviewer maintainability-reviewer ↓ 生成最终审查报告这说明 Plugin 是一种组合式能力包Plugin ≠ 一个 Prompt Plugin 一组可协同运行的 Agent 能力6、用户 Skill 与 Plugin Skill 的区别项目中的直接 Skillproject/.claude/skills/code-review/SKILL.mdPlugin 中的 Skillinstalled-plugin/skills/code-review/SKILL.md二者内容格式可能相近但生命周期不同。维度项目 SkillPlugin Skill维护者项目团队Plugin 发布者分发方式Git 仓库提交Marketplace 安装版本管理跟随项目版本Plugin 版本命名空间通常直接名称通常带 Plugin 作用域启停方式文件或 Skill 配置Plugin 管理更新方式Git 更新Marketplace 更新适用范围当前项目用户、项目或本地安装作用域官方文档明确指出Plugin Skill 不受普通skillOverrides控制而应通过/plugin管理。这进一步说明 Plugin Skill 在 Claude Code 内部并不只是被复制成普通 Skill而是保留了 Plugin 来源和管理边界。7、Plugin 的安装作用域在安装 Claude Code Plugin 时目前可以选择Install for you → 用户级在所有项目可用 Install for this project → 项目级可与项目协作者共享 Install locally → 仅当前用户、仅当前仓库这是官方 IDE 文档列出的三种安装方式。逻辑上可以对应为User Scope Project Scope Local Project Scope这种设计与settings.json和settings.local.json的分层是一致的。用户级适合 个人常用工具 通用代码审查 个人写作和调试习惯项目级适合 团队统一工作流 项目专用部署能力 统一审查规范 项目 MCP 集成本地项目级适合 本机实验 尚未准备共享的 Plugin 个人凭据相关能力 调试版本后续分析安装流程时需要进一步确认三个作用域分别写入哪些状态文件以及是否直接把 Plugin 内容复制到项目目录。四、Marketplace 的安装1、Marketplace 的添加与使用入口Marketplace 可以通过 Claude Code 的/plugin系统管理。官方文档提供的典型流程是/plugin marketplace add anthropics/claude-plugins-official /plugin marketplace update claude-plugins-official /plugin install skill-creatorclaude-plugins-official /reload-plugins这套流程说明 Claude Code 至少分为四个阶段添加 Marketplace Source ↓ 更新 Marketplace Catalog ↓ 安装指定 Plugin ↓ 重新加载 Plugin 能力Skill 官方文档也明确指出Plugin 安装后可以通过/reload-plugins让当前会话识别新 Skill。在 IDE 中Marketplace 还可以通过图形界面添加支持GitHub Repository URL Local Path添加或删除后界面会提示重启 Claude Code 以应用更新。2、内置 Marketplace 与官方 Marketplace不是完全相同的概念这里容易产生误解。“官方 Marketplace”表示由 Anthropic 维护的 Marketplace Source但这并不一定意味着所有 Claude Code 安装都永远自动内置并启用官方文档仍然提供了手动添加命令/plugin marketplace add anthropics/claude-plugins-official并说明当 Claude Code 报告 Marketplace 不存在时需要执行这一命令。所以更准确的说法是claude-plugins-official → 官方维护的 Marketplace 是否已注册到当前机器 → 取决于安装版本、本地状态和初始化情况“官方”描述的是信任和维护关系不等同于“必然已在本地注册”。3、企业如何控制 MarketplaceClaude Code 已经提供了企业级 Marketplace 治理能力。例如托管配置中的strictKnownMarketplaces可以限制用户允许添加的 Marketplace Source。官方说明中它具有几个关键特征只能在 managed-settings.json 中设置 用户和项目不能覆盖 在网络和文件系统操作前执行校验 支持精确匹配 Git Source 的 ref 和 path例如企业可以{strictKnownMarketplaces:[]}这意味着完全禁止用户添加新的 Marketplace。也可以只允许公司仓库{strictKnownMarketplaces:[{source:github,repo:company/internal-agent-plugins}]}其核心思想是Marketplace Allowlist ↓ Plugin Source Allowlist ↓ Plugin Enable Policy ↓ Runtime PermissionMarketplace 治理并不等于运行权限治理但它可以在供应链最前端阻止未知代码进入本地。五、从静态结构看 Claude Code 的整体设计到这里可以把 Claude Code 的扩展体系归纳为七层。第一层Marketplace Source GitHub Git URL Local Path 企业内部仓库 ↓ 第二层Marketplace Catalog .claude-plugin/marketplace.json ↓ 第三层Plugin Source 相对目录 独立 Git 仓库 Git 子目录 固定 Commit ↓ 第四层Plugin Manifest .claude-plugin/plugin.json ↓ 第五层Plugin Components skills/ commands/ agents/ hooks/ .mcp.json ↓ 第六层作用域和配置 User Project Local Project Managed ↓ 第七层Claude Code Harness 发现 加载 注册 命名空间 权限检查 执行这套设计有几个明显特点。1. Marketplace 和 Plugin 解耦Marketplace 只负责发现和定位Plugin 可以独立维护。2. Plugin 是真正的分发单元Skill 只是 Plugin 的一种组件。3. 采用约定优于配置Plugin 中大量能力通过固定目录组织skills/ commands/ agents/而不是把所有文件逐个写进 Manifest。4. Git 是核心供应链基础设施Marketplace 和 Plugin 都天然适合使用 GitRepository Ref SHA Subdirectory5. 运行时权限仍由 Harness 掌握Plugin 可以提供能力但最终能否读写文件、执行 Shell、访问网络仍然需要经过 Claude Code 权限层。六、这套体系的几个关键问题虽然整体设计已经比较完整但从当前静态结构看仍有一些值得继续追踪的问题。1. Marketplace 与 Plugin Manifest 冲突时谁优先marketplace.json version 1.2.0 plugin.json version 1.1.0Claude Code 是否拒绝安装还是选择其中一个版本2.sha是否真正构成完整的版本锁定如果 Marketplace Entry 指向一个固定 SHA是否安装时强制验证 是否缓存该 Commit Marketplace 更新时如何处理 能否自动升级3. Plugin 目录是复制、缓存还是直接引用尤其对于本地 MarketplacePlugin 是否被复制到统一缓存目录 还是直接读取原目录 是否支持符号链接4. 多作用域同版本和不同版本如何合并用户级安装 Plugin 1.0 项目级安装 Plugin 1.2 本地项目级禁用 Plugin最终哪一个生效5. Hook 和 MCP 是否在安装后自动启用这是供应链安全的关键。6. Plugin Skill 如何进入模型上下文Claude Code 是启动时加载全部 Skill 描述 还是按 Plugin 延迟扫描 还是通过专用 Skill Tool 查询这些问题仅靠目录结构无法完全回答需要进入下一阶段的安装和运行时分析。总结Claude Code 的 Skill 并不是一个孤立的 Markdown 文件系统。它属于一套完整的扩展架构Marketplace → 发现和定位能力 Plugin → 打包、安装和管理能力 Skill → 描述完成任务的方法 Command → 提供用户显式入口 Agent → 提供独立执行上下文 Hook → 提供事件自动化 MCP → 提供外部工具 Harness → 负责加载、授权和执行其中两个最重要的配置文件分别是.claude-plugin/marketplace.json → Marketplace 插件目录 .claude-plugin/plugin.json → 单个 Plugin Manifest从架构角度看Claude Code Marketplace 更像一个以 Git 为基础的 Plugin Catalog而不是传统应用商店。Plugin 才是真正的能力分发单元Skill 则是 Plugin 内部用于封装程序性知识和工作流的方法层。下一篇需要沿着这条链继续追踪添加 Marketplace ↓ 本地保存 Marketplace 注册信息 ↓ 更新和缓存 marketplace.json ↓ 安装 Plugin ↓ Plugin 本地落盘 ↓ 记录版本、来源和作用域 ↓ 启用并重新加载也就是深入分析Claude Code 内置与外部 Marketplace 如何发现、安装和落盘重点确认Marketplace 注册信息保存在什么位置Marketplace 仓库如何缓存Plugin 安装目录如何组织用户级、项目级、本地级安装分别写入哪里更新、禁用、卸载和回滚具体如何实现。
从 Skill 说起很多人第一次接触 Claude Code 的 Skill会把它理解为一个放在.claude/skills/目录下的 Markdown 文件。这种理解不能说错但只看到了最表面的一层。在 Claude Code 当前的扩展体系中Skill 并不是最高层级的分发单元。一个完整的能力包还可能包含SkillsSlash CommandsSubagentsHooksMCP ServerLSP ServerSettings可执行脚本和参考资料这些内容通常会被封装成一个Plugin再由Marketplace负责发现、分发和安装。因此Claude Code 的扩展体系更接近Marketplace ↓ Plugin ├── Skill ├── Command ├── Agent ├── Hook ├── MCP Server └── 其他运行时配置 ↓ Claude Code Harness如果想理解 Claude Code 的 Marketplace 与 Skill就不能只研究SKILL.md而要先看清这三个层级Marketplace能力目录和分发源 Plugin安装、启用和版本管理的能力包 SkillPlugin 内部的一种可复用任务能力本文先从文件系统和配置文件入手建立 Claude Code 扩展体系的完整静态结构。一、Claude Code 的整体目录地图1、Claude Code 的能力扩展体系不是单层目录Claude Code 中的能力可能来自多个位置Claude Code 内置能力 用户目录 ~/.claude/ 项目目录 .claude/ 已安装 Plugin来自 Claude 官方 或者 第三方 Marketplace 组织托管配置 当前会话参数这些来源最终都会被 Claude Code Harness 汇总成当前会话可用的能力集合。可以先建立一个简化模型┌─────────────────────────────────────┐ │ Claude Code 内置能力 │ │ Read / Write / Edit / Bash / Agent │ └──────────────────┬──────────────────┘ │ ┌──────────────────▼──────────────────┐ │ 用户级配置 ~/.claude/ │ │ Skills / Agents / Commands / Settings│ └──────────────────┬──────────────────┘ │ ┌──────────────────▼──────────────────┐ │ 项目级配置 project/.claude/ │ │ Skills / Agents / Rules / Settings │ └──────────────────┬──────────────────┘ │ ┌──────────────────▼──────────────────┐ │ Plugin Registry │ │ Marketplace 安装的 Plugin │ └──────────────────┬──────────────────┘ │ ┌──────────────────▼──────────────────┐ │ Managed Settings │ │ 企业策略、白名单和强制插件 │ └──────────────────┬──────────────────┘ ▼ Claude Code Runtime这里有一个非常重要的区别.claude/skills/适合直接放置项目或用户维护的 SkillMarketplace 更适合分发结构完整、具有版本和来源信息的 Plugin。2、Claude Code 的各个能力位置的具体结构Claude Code 没有要求用户理解所有内部目录但从系统角度看可以把相关文件分为四组1. 项目级配置 2. 用户级配置 3. 企业级托管配置 4. Marketplace 与 Plugin 数据一个比较完整的逻辑结构如下project/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── settings.local.json │ ├── skills/ │ │ └── code-review/ │ │ ├── SKILL.md │ │ ├── references/ │ │ ├── scripts/ │ │ └── assets/ │ ├── agents/ │ │ └── reviewer.md │ ├── commands/ │ │ └── review.md │ └── rules/ │ ├── .mcp.json ├── src/ └── tests/用户级配置通常位于~/.claude/ ├── CLAUDE.md ├── settings.json ├── skills/ ├── agents/ ├── commands/ ├── projects/ └── plugins/marketplaces (Marketplace 与 Plugin 数据)企业环境还会存在托管配置文件。官方当前列出的典型位置包括macOS /Library/Application Support/ClaudeCode/managed-settings.json Linux / WSL /etc/claude-code/managed-settings.json Windows C:\Program Files\ClaudeCode\managed-settings.json托管配置拥有最高级别的策略控制能力例如限制用户可以添加哪些 Marketplace。需要注意的是Claude Code 的部分内部缓存和状态文件并不是稳定公共 API。文章后续提到这类目录时应区分公开配置规范 → 可以依赖和版本控制 内部状态与缓存 → 可以观察但不应该作为稳定接口依赖3、各个能力位置中的几个最重要的配置文件1.CLAUDE.mdCLAUDE.md是 Claude Code 的长期上下文文件。它通常用于描述项目架构 编码规范 构建命令 测试方式 依赖选择 禁止事项 提交要求 团队约定例如# Project Instructions ## Architecture This is a Spring Boot WebFlux project. ## Commands - Build: mvn clean package - Test: mvn test - Run: mvn spring-boot:run ## Rules - Do not introduce Spring MVC dependencies. - Use Reactor types for asynchronous APIs. - Add tests for all public service methods.CLAUDE.md不是 Skill也不是 Plugin。它解决的是Claude 在这个项目中应该遵守哪些长期规则Skill 解决的则是Claude 应该怎样完成某一类任务二者的关系可以理解为CLAUDE.md → 项目全局约束 SKILL.md → 特定任务的方法与流程2..claude/settings.json这是项目级 Claude Code 配置。它适合进入版本控制由团队成员共同使用。内容可能包括权限规则 Hook 配置 Plugin 启用状态 环境设置 工具限制 Marketplace 或组织扩展配置示意结构{permissions:{allow:[Bash(mvn test:*),Bash(git diff:*)],deny:[Bash(rm -rf:*)]}}这里的权限不是 Skill 自己的执行权限而是 Claude Code Harness 对工具调用的统一约束。即使某个 Skill 指示 Claude 执行一条命令最后仍然要经过 Claude Code 的权限系统。3..claude/settings.local.json这是当前开发者在当前项目中的本地配置。通常不应提交到版本控制。它适合存放个人权限偏好 本机路径 本地调试配置 只对当前开发者生效的插件状态 临时 Hook可以把两个文件理解为settings.json → 团队共享配置 settings.local.json → 当前开发者的本地覆盖配置4..mcp.json.mcp.json用于声明项目级 MCP Server。示例{mcpServers:{project-database:{type:stdio,command:node,args:[./tools/database-mcp.js]}}}MCP 与 Skill 的关系非常重要MCP Server → 提供工具能力 Skill → 指导 Claude 如何组合这些工具例如PostgreSQL MCP → query_database 工具 database-migration Skill → 数据库迁移的检查、执行和验证流程Claude Code 的 Plugin 也可以携带.mcp.json让插件安装后获得外部工具能力。官方插件仓库给出的标准 Plugin 目录中就把.mcp.json列为可选文件。二、Claude Code 的 Marketplace1、Marketplace 在 Claude Code 中到底是什么Claude Code 的 Marketplace 在 ~/.claude/plugins/marketplaces/ 中 并不只是一个网页。从文件结构上看它更接近一个包含.claude-plugin/marketplace.json的 Git 仓库或本地目录。典型 Marketplace 仓库my-marketplace/ ├── .claude-plugin/ │ └── marketplace.json ├── plugins/ │ ├── code-review/ │ ├── release-manager/ │ └── frontend-design/ ├── external_plugins/ └── README.md其中最关键的文件就是.claude-plugin/marketplace.json它不是某个 Plugin 的配置而是整个 Marketplace 的插件目录插件地图。可以把它理解为Marketplace Catalog其中记录Marketplace 名称 Marketplace 描述 维护者信息 Plugin 列表 每个 Plugin 的来源 分类 主页 版本或 Commit 重命名映射2、marketplace.json的核心结构Claude Code 官方 Marketplace 当前使用的文件位置是.claude-plugin/marketplace.json官方仓库中的顶层结构包括{$schema:https://anthropic.com/claude-code/marketplace.schema.json,name:claude-plugins-official,description:Directory of popular Claude Code extensions,owner:{name:Anthropic,email:supportanthropic.com},renames:{},plugins:[]}官方 Marketplace 当前确实使用了name、description、owner、renames和plugins等字段。1.$schema{$schema:https://anthropic.com/claude-code/marketplace.schema.json}它用于编辑器字段提示JSON 校验Marketplace 结构验证CI 中的格式检查。但需要注意Schema URL 是规范入口不代表 Claude Code 安装时只依赖在线 Schema。Claude Code 自身仍需要内置对应的解析和校验逻辑。2.name{name:claude-plugins-official}Marketplace 名称非常重要因为 Plugin 的完整安装标识通常是plugin-namemarketplace-name例如code-reviewclaude-plugins-official这说明 Claude Code 使用 Marketplace 名称作为命名空间的一部分。仅仅知道 Plugin 名称并不总是足够因为不同 Marketplace 中可能存在同名 Plugin。3.owner{owner:{name:Anthropic,email:supportanthropic.com}}owner描述的是 Marketplace 维护者而不一定是其中所有 Plugin 的作者。因此需要区分Marketplace Owner → 管理整个插件目录 Plugin Author → 开发某一个具体插件一个企业可以维护内部 Marketplace其中包含多个团队开发的 Plugin。4.renames官方 Marketplace 当前还包含renames{renames:{old-plugin-name:new-plugin-name}}这个字段用于处理 Plugin 重命名。它说明 Marketplace 不只是静态列表还承担了部分演进和兼容职责。例如用户原来安装 old-pluginmarketplace Marketplace 更新后 old-plugin → new-plugin如果没有重命名映射Plugin 改名可能导致已安装状态失联更新失败用户需要手动卸载重装项目配置继续引用旧名称。5.plugins这是 Marketplace 的核心。一个简单的 Plugin Entry 可能是{name:code-review,description:Automated code review for pull requests,author:{name:Anthropic},source:./plugins/code-review,category:productivity,homepage:https://github.com/example/code-review}官方 Marketplace 中的code-review就使用了相对目录作为 Source。这种方式表示Marketplace 仓库 └── plugins/ └── code-review/即 Plugin 内容与 Marketplace Catalog 位于同一个仓库中。3、Plugin Source 的几种形态Claude Code Marketplace 的一个重要设计是 Plugin 不一定必须与 Marketplace 位于同一个仓库。从当前官方 Marketplace 可以观察到几种 Source 形式。1. 相对目录{source:./plugins/code-review}适合单仓库 Marketplace 企业内部插件仓库 官方维护的插件集合优点是结构简单Marketplace 和 Plugin 可以一起版本管理。缺点是 Marketplace 仓库可能越来越大。2. 独立 Git URL{source:{source:url,url:https://github.com/example/plugin.git,sha:...}}官方 Marketplace 中已经存在这种形式并使用sha固定具体 Commit。它适合Plugin 独立维护 Marketplace 只维护索引 第三方厂商发布自己的插件仓库这种模式下Marketplace → 只提供目录和可信入口 Plugin Repository → 独立维护代码和版本3. Git 仓库子目录{source:{source:git-subdir,url:https://github.com/example/plugins.git,path:plugins/security-review,ref:v1.5.5,sha:...}}官方 Marketplace 当前也使用了git-subdir、path、ref和sha组合。这种模式适合 Monorepocompany-agent-plugins/ ├── plugins/ │ ├── java-review/ │ ├── database/ │ └── release/ └── shared/Marketplace 可以只安装其中一个子目录而不必把整个仓库都当成一个 Plugin。4、Marketplace 更接近“Git Catalog”而不是传统应用商店从marketplace.json的设计可以看出Claude Code Marketplace 当前更接近Homebrew Tap Git Plugin Catalog Package Source Index而不是传统意义上的App Store VS Code Marketplace Chrome Web Store原因在于它的核心结构是Marketplace Git Source ↓ marketplace.json ↓ Plugin Source ↓ Plugin Repository 或目录Marketplace 主要解决Plugin 从哪里发现 Plugin 的名称和描述 Plugin 的代码在哪里 Plugin 属于什么分类 Plugin 对应哪个版本或 Commit而评论、付费、复杂推荐、下载统计等传统商店功能并不是本地 Marketplace 文件的核心职责。5、官方 Marketplace 的仓库分为内部开发和维护和第三方提供Anthropic 当前维护了官方 Plugin Marketplace其仓库结构明确区分plugins/ → Anthropic 内部开发和维护的 Plugin external_plugins/ → 合作伙伴和社区提供的第三方 Plugin官方仓库文档也明确说明了这一分类。整体结构可以抽象为claude-plugins-official/ ├── .claude-plugin/ │ └── marketplace.json ├── plugins/ │ ├── code-review/ │ ├── commit-commands/ │ ├── plugin-dev/ │ └── skill-creator/ ├── external_plugins/ │ ├── playwright/ │ ├── serena/ │ └── ... └── README.md但并非marketplace.json中的所有 Plugin 都必须真实存在于这两个目录。一些 Plugin Entry 会引用外部 Git 仓库。所以更准确的理解是官方 Marketplace Catalog ├── 官方仓库内置 Plugin ├── 官方仓库中的外部 Plugin 镜像或目录 └── 指向第三方独立仓库的 Plugin Entry三、Claude Code 的 Plugin1、Plugin 的标准目录结构一个 Plugin 的核心结构如下plugin-name/ ├── .claude-plugin/ │ └── plugin.json ├── .mcp.json ├── commands/ ├── agents/ ├── skills/ └── README.md这是 Anthropic 官方 Plugin 仓库给出的标准结构。更完整的 Plugin 还可能包含plugin-name/ ├── .claude-plugin/ │ └── plugin.json │ ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── references/ │ │ ├── scripts/ │ │ └── assets/ │ └── security-review/ │ └── SKILL.md │ ├── commands/ │ ├── review.md │ └── review-pr.md │ ├── agents/ │ ├── code-reviewer.md │ └── security-reviewer.md │ ├── hooks/ │ └── hooks.json │ ├── .mcp.json ├── scripts/ ├── README.md └── LICENSE这说明一个 Plugin 可以是一组相互配合的能力而不只是一个 Skill。2、plugin.json的角色每个标准 Plugin 都需要.claude-plugin/plugin.json它是 Plugin Manifest。其作用类似package.json pom.xml plugin.yaml extension.json一个简化示例{name:code-review,version:1.0.0,description:Automated code review workflows,author:{name:Example Team}}需要特别注意marketplace.json → 描述 Marketplace 中有哪些 Plugin plugin.json → 描述当前目录本身是什么 Plugin两者职责不同。可以类比 Mavenmarketplace.json ≈ Repository Index plugin.json ≈ 单个 Artifact 的 Manifest3、Marketplace Entry 与plugin.json为什么会重复你可能会发现marketplace.json 中有 name、description、author、version plugin.json 中也有 name、description、author、version这并不是完全重复而是两个阶段的数据。Marketplace 阶段在 Plugin 尚未安装时Claude Code 需要展示Plugin 名称 简介 作者 分类 来源 主页因此这些字段必须出现在marketplace.json中否则用户还没有下载 Plugin就无法浏览其信息。Plugin 运行阶段Plugin 安装以后Claude Code 需要从本地目录识别这是什么 Plugin 版本是多少 有哪些元信息 是否符合 Plugin 结构因此 Plugin 自身还需要plugin.json。可以理解为Marketplace Entry → 安装前元数据 plugin.json → 安装后本地 Manifest这两个文件之间理论上应该保持一致但也存在漂移风险Marketplace 声明版本 1.2 Plugin Manifest 声明版本 1.1后续研究需要重点确认 Claude Code 遇到不一致时以哪个为准以及是否执行一致性校验。4、Plugin 内各组件分别是什么1. Skillskills/ └── code-review/ └── SKILL.mdSkill 用于描述适用场景 执行方法 工作流程 参考知识 工具组合 验证方式 输出格式它主要是程序性知识和任务方法。2. Commandcommands/ └── review.mdCommand 提供用户显式调用入口例如/code-review:reviewPlugin 中的能力通常带有命名空间GitHub Actions 官方文档也使用/plugin-name:skill-name来调用 Plugin 中的 Skill。命名空间可以避免不同 Plugin 都定义 /review导致的冲突。3. Agentagents/ └── code-reviewer.mdAgent 是一个专用 Subagent 定义。它拥有独立角色 独立提示词 独立上下文 可配置的工具集合Plugin Agent 安装后会自动与用户自定义 Agent 一起加载并以带作用域的名称出现在 Agent 选择中。但出于安全考虑Plugin 中的 Agent 不能通过 Frontmatter 自行启用hooks、mcpServers或permissionMode。这些字段在 Plugin Agent 中会被忽略。这说明 Claude Code 对 Plugin 能力并非完全无条件信任。4. HookHook 用于在生命周期事件发生时执行动作。例如文件编辑后自动格式化 执行命令前检查 任务结束后运行测试 提交前运行 LintHook 与 Skill 最大区别是Skill → 模型判断和遵循 Hook → 事件触发Hook 更确定也更危险因为它可能在事件发生时直接执行 Shell 或 HTTP 请求。5. MCP ServerPlugin 根目录可以包含.mcp.json它用于给 Plugin 提供真正的外部工具例如GitHub API 数据库 浏览器 监控平台 云服务 内部业务系统因此一个完整 Plugin 可以形成MCP → 提供工具 Skill → 提供使用方法 Command → 提供用户入口 Agent → 提供独立执行者 Hook → 提供生命周期自动化5、一个完整 Plugin 的逻辑结构以代码审查 Plugin 为例code-review-plugin/ ├── .claude-plugin/ │ └── plugin.json │ ├── skills/ │ └── review-code/ │ ├── SKILL.md │ └── references/ │ ├── security.md │ └── java-style.md │ ├── commands/ │ └── review.md │ ├── agents/ │ ├── correctness-reviewer.md │ ├── security-reviewer.md │ └── maintainability-reviewer.md │ ├── hooks/ │ └── hooks.json │ └── README.md它的执行关系可能是用户执行 /code-review:review ↓ Command 加载代码审查任务说明 ↓ Claude 读取 review-code Skill ↓ Skill 要求 1. 获取 Diff 2. 识别改动模块 3. 并行启动审查 Agent 4. 合并结论 5. 按置信度过滤 ↓ correctness-reviewer security-reviewer maintainability-reviewer ↓ 生成最终审查报告这说明 Plugin 是一种组合式能力包Plugin ≠ 一个 Prompt Plugin 一组可协同运行的 Agent 能力6、用户 Skill 与 Plugin Skill 的区别项目中的直接 Skillproject/.claude/skills/code-review/SKILL.mdPlugin 中的 Skillinstalled-plugin/skills/code-review/SKILL.md二者内容格式可能相近但生命周期不同。维度项目 SkillPlugin Skill维护者项目团队Plugin 发布者分发方式Git 仓库提交Marketplace 安装版本管理跟随项目版本Plugin 版本命名空间通常直接名称通常带 Plugin 作用域启停方式文件或 Skill 配置Plugin 管理更新方式Git 更新Marketplace 更新适用范围当前项目用户、项目或本地安装作用域官方文档明确指出Plugin Skill 不受普通skillOverrides控制而应通过/plugin管理。这进一步说明 Plugin Skill 在 Claude Code 内部并不只是被复制成普通 Skill而是保留了 Plugin 来源和管理边界。7、Plugin 的安装作用域在安装 Claude Code Plugin 时目前可以选择Install for you → 用户级在所有项目可用 Install for this project → 项目级可与项目协作者共享 Install locally → 仅当前用户、仅当前仓库这是官方 IDE 文档列出的三种安装方式。逻辑上可以对应为User Scope Project Scope Local Project Scope这种设计与settings.json和settings.local.json的分层是一致的。用户级适合 个人常用工具 通用代码审查 个人写作和调试习惯项目级适合 团队统一工作流 项目专用部署能力 统一审查规范 项目 MCP 集成本地项目级适合 本机实验 尚未准备共享的 Plugin 个人凭据相关能力 调试版本后续分析安装流程时需要进一步确认三个作用域分别写入哪些状态文件以及是否直接把 Plugin 内容复制到项目目录。四、Marketplace 的安装1、Marketplace 的添加与使用入口Marketplace 可以通过 Claude Code 的/plugin系统管理。官方文档提供的典型流程是/plugin marketplace add anthropics/claude-plugins-official /plugin marketplace update claude-plugins-official /plugin install skill-creatorclaude-plugins-official /reload-plugins这套流程说明 Claude Code 至少分为四个阶段添加 Marketplace Source ↓ 更新 Marketplace Catalog ↓ 安装指定 Plugin ↓ 重新加载 Plugin 能力Skill 官方文档也明确指出Plugin 安装后可以通过/reload-plugins让当前会话识别新 Skill。在 IDE 中Marketplace 还可以通过图形界面添加支持GitHub Repository URL Local Path添加或删除后界面会提示重启 Claude Code 以应用更新。2、内置 Marketplace 与官方 Marketplace不是完全相同的概念这里容易产生误解。“官方 Marketplace”表示由 Anthropic 维护的 Marketplace Source但这并不一定意味着所有 Claude Code 安装都永远自动内置并启用官方文档仍然提供了手动添加命令/plugin marketplace add anthropics/claude-plugins-official并说明当 Claude Code 报告 Marketplace 不存在时需要执行这一命令。所以更准确的说法是claude-plugins-official → 官方维护的 Marketplace 是否已注册到当前机器 → 取决于安装版本、本地状态和初始化情况“官方”描述的是信任和维护关系不等同于“必然已在本地注册”。3、企业如何控制 MarketplaceClaude Code 已经提供了企业级 Marketplace 治理能力。例如托管配置中的strictKnownMarketplaces可以限制用户允许添加的 Marketplace Source。官方说明中它具有几个关键特征只能在 managed-settings.json 中设置 用户和项目不能覆盖 在网络和文件系统操作前执行校验 支持精确匹配 Git Source 的 ref 和 path例如企业可以{strictKnownMarketplaces:[]}这意味着完全禁止用户添加新的 Marketplace。也可以只允许公司仓库{strictKnownMarketplaces:[{source:github,repo:company/internal-agent-plugins}]}其核心思想是Marketplace Allowlist ↓ Plugin Source Allowlist ↓ Plugin Enable Policy ↓ Runtime PermissionMarketplace 治理并不等于运行权限治理但它可以在供应链最前端阻止未知代码进入本地。五、从静态结构看 Claude Code 的整体设计到这里可以把 Claude Code 的扩展体系归纳为七层。第一层Marketplace Source GitHub Git URL Local Path 企业内部仓库 ↓ 第二层Marketplace Catalog .claude-plugin/marketplace.json ↓ 第三层Plugin Source 相对目录 独立 Git 仓库 Git 子目录 固定 Commit ↓ 第四层Plugin Manifest .claude-plugin/plugin.json ↓ 第五层Plugin Components skills/ commands/ agents/ hooks/ .mcp.json ↓ 第六层作用域和配置 User Project Local Project Managed ↓ 第七层Claude Code Harness 发现 加载 注册 命名空间 权限检查 执行这套设计有几个明显特点。1. Marketplace 和 Plugin 解耦Marketplace 只负责发现和定位Plugin 可以独立维护。2. Plugin 是真正的分发单元Skill 只是 Plugin 的一种组件。3. 采用约定优于配置Plugin 中大量能力通过固定目录组织skills/ commands/ agents/而不是把所有文件逐个写进 Manifest。4. Git 是核心供应链基础设施Marketplace 和 Plugin 都天然适合使用 GitRepository Ref SHA Subdirectory5. 运行时权限仍由 Harness 掌握Plugin 可以提供能力但最终能否读写文件、执行 Shell、访问网络仍然需要经过 Claude Code 权限层。六、这套体系的几个关键问题虽然整体设计已经比较完整但从当前静态结构看仍有一些值得继续追踪的问题。1. Marketplace 与 Plugin Manifest 冲突时谁优先marketplace.json version 1.2.0 plugin.json version 1.1.0Claude Code 是否拒绝安装还是选择其中一个版本2.sha是否真正构成完整的版本锁定如果 Marketplace Entry 指向一个固定 SHA是否安装时强制验证 是否缓存该 Commit Marketplace 更新时如何处理 能否自动升级3. Plugin 目录是复制、缓存还是直接引用尤其对于本地 MarketplacePlugin 是否被复制到统一缓存目录 还是直接读取原目录 是否支持符号链接4. 多作用域同版本和不同版本如何合并用户级安装 Plugin 1.0 项目级安装 Plugin 1.2 本地项目级禁用 Plugin最终哪一个生效5. Hook 和 MCP 是否在安装后自动启用这是供应链安全的关键。6. Plugin Skill 如何进入模型上下文Claude Code 是启动时加载全部 Skill 描述 还是按 Plugin 延迟扫描 还是通过专用 Skill Tool 查询这些问题仅靠目录结构无法完全回答需要进入下一阶段的安装和运行时分析。总结Claude Code 的 Skill 并不是一个孤立的 Markdown 文件系统。它属于一套完整的扩展架构Marketplace → 发现和定位能力 Plugin → 打包、安装和管理能力 Skill → 描述完成任务的方法 Command → 提供用户显式入口 Agent → 提供独立执行上下文 Hook → 提供事件自动化 MCP → 提供外部工具 Harness → 负责加载、授权和执行其中两个最重要的配置文件分别是.claude-plugin/marketplace.json → Marketplace 插件目录 .claude-plugin/plugin.json → 单个 Plugin Manifest从架构角度看Claude Code Marketplace 更像一个以 Git 为基础的 Plugin Catalog而不是传统应用商店。Plugin 才是真正的能力分发单元Skill 则是 Plugin 内部用于封装程序性知识和工作流的方法层。下一篇需要沿着这条链继续追踪添加 Marketplace ↓ 本地保存 Marketplace 注册信息 ↓ 更新和缓存 marketplace.json ↓ 安装 Plugin ↓ Plugin 本地落盘 ↓ 记录版本、来源和作用域 ↓ 启用并重新加载也就是深入分析Claude Code 内置与外部 Marketplace 如何发现、安装和落盘重点确认Marketplace 注册信息保存在什么位置Marketplace 仓库如何缓存Plugin 安装目录如何组织用户级、项目级、本地级安装分别写入哪里更新、禁用、卸载和回滚具体如何实现。
