从 Skill 说起，很多人第一次接触 Claude Code 的 Skill，会把它理解为一个放在 .claude/skills/ 目录下的 Markdown 文件。

这种理解不能说错，但只看到了最表面的一层。

在 Claude Code 当前的扩展体系中，Skill 并不是最高层级的分发单元。一个完整的能力包还可能包含：

• Skills
• Slash Commands
• Subagents
• Hooks
• MCP Server
• LSP Server
• Settings
• 可执行脚本和参考资料

这些内容通常会被封装成一个 Plugin，再由 Marketplace 负责发现、分发和安装。

因此，Claude Code 的扩展体系更接近：

Marketplace
    ↓
Plugin
    ├── Skill
    ├── Command
    ├── Agent
    ├── Hook
    ├── MCP Server
    └── 其他运行时配置
            ↓
Claude Code Harness

如果想理解 Claude Code 的 Marketplace 与 Skill，就不能只研究 SKILL.md，而要先看清这三个层级：

Marketplace：能力目录和分发源

Plugin：安装、启用和版本管理的能力包

Skill：Plugin 内部的一种可复用任务能力

本文先从文件系统和配置文件入手，建立 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/ 适合直接放置项目或用户维护的 Skill；Marketplace 更适合分发结构完整、具有版本和来源信息的 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.md

CLAUDE.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 的 Marketplace

1、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": "support@anthropic.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-name@marketplace-name

例如：

code-review@claude-plugins-official

这说明 Claude Code 使用 Marketplace 名称作为命名空间的一部分。

仅仅知道 Plugin 名称并不总是足够，因为不同 Marketplace 中可能存在同名 Plugin。

---

3. owner

{
  "owner": {
    "name": "Anthropic",
    "email": "support@anthropic.com"
  }
}

owner 描述的是 Marketplace 维护者，而不一定是其中所有 Plugin 的作者。

因此需要区分：

Marketplace Owner
    → 管理整个插件目录

Plugin Author
    → 开发某一个具体插件

一个企业可以维护内部 Marketplace，其中包含多个团队开发的 Plugin。

---

4. renames

官方 Marketplace 当前还包含 renames：

{
  "renames": {
    "old-plugin-name": "new-plugin-name"
  }
}

这个字段用于处理 Plugin 重命名。

它说明 Marketplace 不只是静态列表，还承担了部分演进和兼容职责。

例如：

用户原来安装：
old-plugin@marketplace

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 组合。

这种模式适合 Monorepo：

company-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 的 Plugin

1、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

两者职责不同。

可以类比 Maven：

marketplace.json
    ≈ Repository Index

plugin.json
    ≈ 单个 Artifact 的 Manifest

---

3、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. Skill

skills/
└── code-review/
    └── SKILL.md

Skill 用于描述：

适用场景
执行方法
工作流程
参考知识
工具组合
验证方式
输出格式

它主要是程序性知识和任务方法。

---

2. Command

commands/
└── review.md

Command 提供用户显式调用入口，例如：

/code-review:review

Plugin 中的能力通常带有命名空间，GitHub Actions 官方文档也使用：

/plugin-name:skill-name

来调用 Plugin 中的 Skill。

命名空间可以避免：

不同 Plugin 都定义 /review

导致的冲突。

---

3. Agent

agents/
└── code-reviewer.md

Agent 是一个专用 Subagent 定义。

它拥有：

独立角色
独立提示词
独立上下文
可配置的工具集合

Plugin Agent 安装后会自动与用户自定义 Agent 一起加载，并以带作用域的名称出现在 Agent 选择中。

但出于安全考虑，Plugin 中的 Agent 不能通过 Frontmatter 自行启用 hooks、mcpServers 或 permissionMode。这些字段在 Plugin Agent 中会被忽略。

这说明 Claude Code 对 Plugin 能力并非完全无条件信任。

---

4. Hook

Hook 用于在生命周期事件发生时执行动作。

例如：

文件编辑后自动格式化
执行命令前检查
任务结束后运行测试
提交前运行 Lint

Hook 与 Skill 最大区别是：

Skill
    → 模型判断和遵循

Hook
    → 事件触发

Hook 更确定，也更危险，因为它可能在事件发生时直接执行 Shell 或 HTTP 请求。

---

5. MCP Server

Plugin 根目录可以包含：

.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 的区别

项目中的直接 Skill：

project/.claude/skills/code-review/SKILL.md

Plugin 中的 Skill：

installed-plugin/skills/code-review/SKILL.md

二者内容格式可能相近，但生命周期不同。

维度	项目 Skill	Plugin 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-creator@claude-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、企业如何控制 Marketplace

Claude 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 Permission

Marketplace 治理并不等于运行权限治理，但它可以在供应链最前端阻止未知代码进入本地。

---

五、从静态结构看 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 都天然适合使用 Git：

Repository
Ref
SHA
Subdirectory

5. 运行时权限仍由 Harness 掌握

Plugin 可以提供能力，但最终能否读写文件、执行 Shell、访问网络，仍然需要经过 Claude Code 权限层。

---

六、这套体系的几个关键问题

虽然整体设计已经比较完整，但从当前静态结构看，仍有一些值得继续追踪的问题。

1. Marketplace 与 Plugin Manifest 冲突时谁优先

marketplace.json version = 1.2.0
plugin.json version = 1.1.0

Claude Code 是否拒绝安装，还是选择其中一个版本？

2. sha 是否真正构成完整的版本锁定

如果 Marketplace Entry 指向一个固定 SHA：

是否安装时强制验证
是否缓存该 Commit
Marketplace 更新时如何处理
能否自动升级

3. Plugin 目录是复制、缓存还是直接引用

尤其对于本地 Marketplace：

Plugin 是否被复制到统一缓存目录
还是直接读取原目录
是否支持符号链接

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 安装目录如何组织；
• 用户级、项目级、本地级安装分别写入哪里；
• 更新、禁用、卸载和回滚具体如何实现。