Claude Code 插件与市场是什么？使用、制作与发布

在 Claude Code 中，将技能、子智能体、hooks 和 MCP 配置打包在一起的单位称为插件；列出插件名称及获取来源的目录称为插件市场。两者结合，可以在自己的多个项目中复用流程，也可以与团队共享一套扩展功能。

本文将介绍从安装现成插件，到制作问候技能，再通过目录分发的完整步骤。需要分清三点：（1）插件本体与分发目录属于不同层级；（2）登记目录与安装插件是不同操作；（3）验证命令成功，不代表运行正确或安全。步骤依据官方制作指南。

1. Claude Code 插件是什么？

插件把 Claude Code 扩展功能封装成可共享、可复用的目录。不必包含所有组件：只含一个技能也可以成为插件。

对于个人使用的流程，项目中的 .claude/skills/ 目录可能已经足够。希望将同一套功能分发到多处，并管理更新时，插件更合适。此外还有 LSP 支持、监控等扩展，但它们对运行环境和分发途径有要求。先从小型技能入手，更容易验证。

2. 插件的目录结构

下面是单个插件的标准目录结构。如果提供清单文件，应放在 .claude-plugin/plugin.json；skills/、agents/ 和 hooks/ 则位于插件自身的根目录。分发目录文件 marketplace.json 是另一个层级的文件。后面的示例会将它放在市场根目录下的 .claude-plugin/marketplace.json。

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 此插件的元数据
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

以下是 plugin.json 的示例。仅使用标准目录结构时，可以完全省略清单文件。如果提供了清单，name 为必填项，description 和 version 则是可选项。

{
  "name": "my-first-plugin",
  "description": "用于学习基础的问候插件",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

字段 name 也会成为技能的命名空间，因此此例的调用方式为 /my-first-plugin:hello。对于通过 Git 获取并缓存的分发方式，优先使用 plugin.json 中的版本，其次使用目录中的插件版本。两者都没有版本时，使用解析得到的来源提交 SHA。如果显式版本保持不变，单纯修改代码不会让插件进入可更新状态。直接从本地目录加载和 command 类型来源采用不同规则。详见版本管理文档。

3. 使用 /plugin 与插件市场

先运行 /plugin，即可打开包含 Discover、Installed、Marketplaces 和 Errors 标签页的管理器。基本命令如下：

# 添加市场（分发目录）
/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add ./my-marketplace              # 本地路径
/plugin marketplace add https://example.com/marketplace.json

# 在交互界面选择范围，安装后检查启用状态
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# 通过市场安装的插件（用 --enabled / --disabled 筛选）
/plugin list
/plugin list --enabled

# 按需重新加载变更，并检查结果
/reload-plugins

仅添加目录，不会安装插件。登记后仍需逐个安装。交互式 /plugin install 命令允许在详情界面选择作用范围；shell 命令 claude plugin install 则默认使用 user 范围，可用 --scope 修改。

安装后应检查结果显示的是已激活、等待重新加载，还是加载错误。由于会影响提示缓存，重新加载可能暂缓。在没有终端的会话中，插件的 MCP 变更可能要到下次会话才生效。/plugin list 只涵盖通过市场安装的插件，不会列出所有通过同步或技能目录提供的内容。请核对安装与重新加载的条件；MCP 无法连接时，可参考 MCP 连接错误排查。

4. 什么是插件市场？

插件市场是通过 .claude-plugin/marketplace.json 列出插件及其来源的目录，可通过 Git 仓库、本地路径或托管文件提供。既有官方目录，也有社区目录。

找不到目录时，应检查登记情况；找不到单个插件时，应检查名称和来源。对于内部目录，还必须确保用户既能访问仓库，也能获取插件本体。如果通过 URL 分发 JSON 文件，系统不会从该 URL 的相对路径获取插件内容。

5. 制作并发布自己的插件

以下示例制作一个问候技能。首先准备如下目录结构。外层 .claude-plugin 属于分发目录，内层属于单个插件。请在包含 my-marketplace 的父目录中执行命令。

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-first-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── hello/
                └── SKILL.md

（1）将上一节的 JSON 保存到内层文件 my-marketplace/plugins/my-first-plugin/.claude-plugin/plugin.json。（2）将以下内容保存到 my-marketplace/plugins/my-first-plugin/skills/hello/SKILL.md。本例使用 disable-model-invocation: true，使技能仅在显式调用时使用。

---
name: hello
description: 使用姓名进行简短问候
disable-model-invocation: true
---
简短地向用户问好。
如果提供了参数，在问候中包含该姓名。
参数： $ARGUMENTS

（3）将分发目录写入外层的 my-marketplace/.claude-plugin/marketplace.json。相对 source 路径以市场根目录为基准，而不是 marketplace.json 所在目录。

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "description": "用于练习分发问候技能的目录",
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "使用姓名进行简短问候的技能"
    }
  ]
}

（4）分别验证分发目录与单个插件。前者检查目录结构规范和本地条目的 plugin.json，但不会读取每个技能或 hook 文件；后者还覆盖单个插件标准目录中的文件。两者都不保证实际执行正确或安全。

claude plugin validate ./my-marketplace
claude plugin validate ./my-marketplace/plugins/my-first-plugin

# 将单个插件加载到本次会话中测试
claude --plugin-dir ./my-marketplace/plugins/my-first-plugin

在打开的交互式会话中运行 /my-first-plugin:hello Alex，检查是否得到包含 Alex 的简短问候。功能检查应当查看输出并排查不需要的副作用，而不只是确认命令出现了。如果加载失败，请检查两个 JSON 文件中的名称、source 路径，以及 SKILL.md 的位置和 frontmatter。

（5）如需测试通过目录安装的途径，应先结束上一个测试会话，再启动不带 --plugin-dir 的 Claude Code。以下命令会向你的配置写入登记信息，因此请在练习项目中尝试，并选择安装范围。

/plugin marketplace add ./my-marketplace
/plugin install my-first-plugin@my-plugins
/my-first-plugin:hello Alex

（6）分发时，请将 my-marketplace 的内容作为 Git 仓库根目录发布，并确保用户能够获取。除了目录文件，还必须提交 plugins 目录。用户添加实际的 owner/repo，然后安装相同的 my-first-plugin@my-plugins。这种相对路径结构适用于通过 Git 或本地目录登记，不能原样用于单独的 marketplace.json URL。详见目录的制作、分发与验证。

通过自己的 Git 仓库分发，无须申请官方目录收录。如果还希望被社区目录收录，个人作者可使用 Console 投稿表单。claude.ai 上的表单则要求 Team/Enterprise 组织及相应管理权限。向社区投稿，与进入 Anthropic 策划维护的官方目录是两回事。

6. 安装范围与安全

安装范围包括 user（自己的所有项目）、project（共享项目设置）和 local（仅自己在当前项目中使用）。应区分交互式界面的范围选择与 shell CLI 默认的 user 范围。托管设置由管理员控制，并限制用户修改配置。

团队可以使用 extraKnownMarketplaces 与 enabledPlugins，在 .claude/settings.json 中共享来源及启用状态。但写好共享设置，不等于所有成员的电脑都已完成安装。每位成员仍需安装外部来源的插件。信任项目后，应在各环境检查目录登记、访问权限与安装结果。

总结

插件是扩展功能的分发单位，市场是插件目录。用户先登记目录 → 逐个安装插件 → 检查启用状态与行为；作者则准备插件与目录 → 分别验证 → 调用功能 → 通过可访问的仓库分发。核对作用范围、访问权限和更新采用的版本，有助于在其他环境复现这套配置。

官方目录的自动登记有条件，经过审查的项目也没有无条件的行为保证。先引入一项所需功能，验证结果后再扩展。相关机制可参阅 Claude Code hooks、Claude Agent Skills、MCP 与 Claude Code Artifacts。

常见问题

问：插件与技能有什么区别？
答：技能是要执行的流程；插件是分发单位，可将技能与 hooks、MCP 配置等组件打包。显式调用插件技能时，使用 /plugin-name:skill-name。是否支持自动选择，取决于说明和设置。

问：找不到官方插件市场。
答：官方 claude-plugins-official 会在首次交互式启动时自动登记，但先前的非交互式使用、网络限制或托管策略可能阻止登记。在允许的环境中，可尝试 /plugin marketplace add anthropics/claude-plugins-official。仅登记市场，不会安装其中的单个插件。

问：任何人都能分发自己制作的插件吗？
答：一种方式是将插件与目录放入自己可访问的 Git 仓库，并确保使用者也能获取。社区目录收录需要另行投稿，个人作者可使用 Console 表单；claude.ai 投稿途径则有组织和权限要求。还应确认目录中的 source 指向插件的实际位置。

问：为什么修改代码后，插件没有更新？
答：对于通过 Git 获取并缓存的分发方式，plugin.json 的版本优先级最高。如果它不变，仅修改目录版本不会更新插件。两处都未提供版本时，使用解析得到的 Git 提交 SHA，但更新操作和来源 ref 也有影响。直接从本地目录加载、归档来源及 command 类型来源采用不同规则。

问：validate 成功就说明插件安全吗？
答：不是。结构与配置验证，不等同于实际行为和安全测试。只验证目录，不会检查技能正文等文件。还应验证单个插件，并测试功能与副作用。社区收录审查也不能代替对发布者和所含代码的检查。