Claude Code 配置什么时候该做成插件？

你在自己电脑上搭好的命令、Hook 和子代理，单机跑起来非常顺。一旦想把这套工作流推广给整个团队，各种手动同步问题就接踵而至：

• 小王只复制了斜杠命令，漏掉了对应的模板文件；
• 小李的本地拦截 Hook 还是上个月的老逻辑；
• 小张的环境变量名跟脚本里写的完全对不上。

方法本身很靠谱，但分发手段太零散，每个人手里的工具状态都不一样，排查起来很辛苦。Plugin 就是为了解决这种“口口相传、人肉复制”的局面：把一个场景所需的命令、代理、Hook、模板和 MCP 连接打包成一个分发单元，团队成员一行命令装好，升级、禁用和回滚也走同一套机制。

反过来的问题同样常见。方法还没在真实任务里打磨结实就打成插件，每改一行都要发新版本、提醒全员更新，等于提前给自己套上了版本分发的负担。

所以先回答“什么时候打包”：配置还在变，就留在项目的 .claude/ 目录里随仓库提交；方法稳定了、另一个仓库也要用，再升级为插件。打包时一个插件只服务一个场景，目录、事件绑定、命名空间和版本号都按使用者的调用方式来定。

01 先在项目里养熟，再打包

先用下面这张表判断是否该上插件：

插件化之前，先在真实任务中验证工作流。试想一下：别人刚装上你的插件跑了两趟，就来反馈参数传不进去、严重程度评级不合理、模板字段缺了几项。你改了一行，就得重新打 tag、发新版本，再在群里提醒所有人更新。核心方法都还没在真实场景里打磨结实，就先背上了一层版本分发的负担。

更务实的路径是先在本地养熟：把命令、代理和模板放在当前项目的 .claude/ 目录下，跟着 Git 仓库一起提交，大家每天在真实的 PR 和排错中用它、提意见、完善它。小团队在单个项目中工作时，通过仓库共享这些配置就够了。

等这套机制的核心结构已经稳定一段时间、不再频繁调整，并且确实有别的项目也要复用，再把它打包成独立插件。Claude Code 的功能总览给出的信号也很具体：第二个仓库需要同样的配置时，打包成插件。

一个插件应围绕一个明确场景。按工作流拆分，能让权限、版本和使用入口保持清楚，例如 pr-review、devops-automation、documentation、security-audit、data-reporting。

02 目录与组件：放对位置，还要写清谁调用

Plugin 是一组能力的安装和分发单元。下面展示可选组件的放置方式，不要求每个插件创建全部目录。最小项目可先包含清单和一个命令，验证能加载后再增加组件。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── report-writer/
│       └── SKILL.md
├── commands/
│   └── review.md
├── agents/
│   ├── security-reviewer.md
│   └── test-checker.md
├── hooks/
│   ├── hooks.json
│   └── pre-check.js
├── .mcp.json
├── .lsp.json
├── settings.json
├── templates/
├── scripts/
└── docs/

各部分职责分工如下：

按 Claude Code 的插件组件说明，新写的命令建议用 Skill 的形式放在 skills/ 下，commands/ 留给已有的文件。

插件的 settings.json 也有自己的字段范围。需要什么默认设置，就核对它是否支持，不能把整份项目设置复制进去，期待任意覆盖用户权限。

看完目录，再顺着调用找一次：清单在 .claude-plugin/，组件在插件根目录。命令或 Skill 要引用模板和脚本，Hook 要通过 hooks/hooks.json 绑定事件。文件放到正确目录后，还要写清楚由谁来调用。

脚本能手动运行，只证明脚本入口可用。若插件安装后 Hook 从未触发，还需用 hooks/hooks.json 明确事件、匹配工具与执行命令，例如：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-check.js\""
      }]
    }]
  }
}

接下来用 /hooks 看绑定是否加载，再做一次无害调用，看脚本有没有真的运行。若绑定看得到却没有结果，就沿匹配条件和执行路径排查；先把加载与执行分开，才知道卡在哪一步。仅因目录叫 hooks，里面的脚本并不会自动运行。

03 命令要带命名空间

插件的命令安装后通过插件命名空间调用，命名空间能避免多个插件出现同名入口：

/pr-review:review
/pr-review:check-security
/pr-review:check-tests

一个 PR 审查命令可以这样写：

---
argument-hint: "[PR number or branch]"
allowed-tools: Read Grep Bash
---

# Review PR

请审查指定 PR 或当前分支的变更。

## 流程

1. 收集变更范围。
2. 调用 security-reviewer 检查安全风险。
3. 调用 test-checker 检查测试缺口。
4. 调用 performance-analyzer 检查性能风险。
5. 汇总结果，按严重程度排序。

## 输出

- 高风险问题
- 中低风险问题
- 测试缺口
- 建议修改
- 建议验证命令

沿这条命令往下看，用户先指定对象，命令再安排各项检查，最后汇总。入口需要把顺序说清；具体怎样审安全、怎样判断测试缺口，可以留给 agents、Skills 或脚本。这样调整某一项审查标准时，才能找到它实际保存的位置。

pr-review 和 legacy-tools 都可能提供 review 命令，且严重程度标准不同。使用 /pr-review:review 与 /legacy-tools:review，可以明确选用哪套方法。眼下只有一个 review 入口时，短形式也许够用；以后装了另一个插件，同样的名字就可能指向不同方法。团队说明里保留完整命名空间，成员照着调用时就能选中同一套标准。

插件里打包子代理时，工具权限越克制越好。安全审计、代码审查和架构分析这类观察角色，只给读取与搜索工具；只有真正负责写代码、跑部署流水线的执行角色，才给写入或调用外部系统的能力。

04 清单与版本号：按调用方是否要改来定

插件清单放在 .claude-plugin/plugin.json：

{
  "name": "pr-review",
  "description": "团队 PR 审查工作流，包含审查命令、安全代理、测试检查和结果模板。",
  "version": "1.0.0",
  "author": {
    "name": "Team"
  }
}

清单至少要回答使用者的这些问题：插件叫什么、解决什么问题、当前版本是什么、包含哪些能力、需要哪些外部依赖、是否需要用户配置。

插件版本建议使用语义化版本：

用调用方是否需要调整来判断：

这三种变化都可以笼统地叫作“更新”，对调用方的影响却不同。模板改错字，原脚本照常运行；参数从 PR 号改成分支，调用脚本就得跟着改。命令名、参数、权限或输出变化时，沿真实调用检查一次，再决定版本，不能只根据发布说明里的“修复”或“新增”判断。

05 只在需要时加组件

Plugin 通过组件分工组合一条完整工作流：

• Skill 负责专项方法。
• Hook 负责事件边界上的自动检查。
• MCP 负责外部工具和实时数据。
• Command 负责用户入口。
• Agent 负责专业角色。

以一个 PR 审查插件为例，它可以包含：

pr-review/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review-pr.md
│   ├── check-security.md
│   └── check-tests.md
├── agents/
│   ├── security-reviewer.md
│   ├── test-checker.md
│   └── performance-analyzer.md
├── hooks/
│   └── pre-review.js
└── templates/
    └── review-report.md

完整工作流：

1. 用户调用 /pr-review:review-pr。
2. 命令显式调用 pre-review.js，检查当前是否在有效项目中。
3. security-reviewer 分析安全风险。
4. test-checker 检查测试覆盖。
5. performance-analyzer 检查性能风险。
6. 命令使用 review-report 模板汇总。
7. 输出修改建议和验证命令。

上面的 pre-review.js 只是脚本文件；若希望由事件自动触发，还需补充 hooks/hooks.json。这个插件只负责 PR 审查，部署和事故响应属于不同权限与生命周期，由独立插件承载。

文档插件也一样：命令负责生成、同步与校验；api-documenter、code-commentator、example-generator 三个代理分别处理 API 文档、注释建议和使用示例；technical-writing Skill 保存写法；模板统一 ADR、端点与函数说明。模板列好字段后，再取一段当前代码生成文档，逐项对照参数、响应和示例。字段齐全，内容也可能仍是旧版，真正维持文档可用的，是每次都回到当前代码核对。

插件还可以包含 LSP 配置，让 Claude Code 获得更好的代码诊断、导航和符号信息，必填项是启动程序 command 和扩展名到语言 ID 的 extensionToLanguage。先看插件任务会不会用到诊断、跳转或符号信息；如果只是按模板组织一份报告，增加语言服务器也不会改善报告。确实需要时再接入，普通流程就能少承担一项安装和启动依赖。

会操作部署环境的插件（比如 DevOps 插件的部署、回滚、事故响应），要设置人工确认点：部署前确认环境，回滚前确认版本，生产操作前展示影响范围。若部署流程需要确认，先给出可供检查的计划，例如：

• 目标：staging，来源为本次参数。
• 版本：当前 v2.3.1，计划部署 v2.3.2。
• 范围：3 个服务重启，无数据库变更。
• 预计影响：API 中断约 40 秒。

这里的版本、3 个服务和约 40 秒都只是示例，实际计划要根据本次检查填写。不能把样例里的“无数据库变更”直接沿用到每次部署；目标、版本和影响范围清楚后，再按流程确认继续。

06 分发渠道与托管设置

插件常见来源有官方目录、社区目录、组织内部市场、本地路径和包管理器。准备分发时，先确认团队从哪里取得这套流程。组织市场或本地受控渠道，能让成员沿同一可信来源安装；再配合明确版本，才容易核对大家用的是否是同一份内容。

市场定义可以放在 .claude-plugin/marketplace.json：

{
  "name": "my-team-plugins",
  "owner": {"name": "DevTools Team"},
  "plugins": [
    {
      "name": "code-standards",
      "source": "./plugins/code-standards",
      "description": "团队代码规范检查插件",
      "version": "1.2.0"
    }
  ]
}

先从使用者的安装过程看这两份清单：市场条目告诉他去哪里取得插件，目录中的 plugin.json 再说明插件本身。市场清单能解析，插件本身却可能取不到；示例用了相对来源，市场仓库内就必须存在对应目录。组件定义以插件清单为准，避免两边各维护一份。

常用管理命令如下，各自演示一个动作，按需单独运行：

claude plugin marketplace add ./team-marketplace
claude plugin install code-standards@my-team-plugins
claude plugin list
claude plugin disable code-standards@my-team-plugins
claude plugin validate ./my-plugin

本地开发时可以用 claude --plugin-dir ./my-plugin 直接加载插件目录，修改后用 /reload-plugins 在当前会话里重新读取。

团队或组织可以通过托管设置控制插件使用：enabledPlugins 按 插件名@市场名 开关具体插件，strictKnownMarketplaces 限定可以添加和安装的市场来源，blockedMarketplaces 屏蔽指定的市场来源。如果策略要求“只允许经过审核的插件”，仅把几个标准插件设为启用，还没回答其他插件能否安装。启用状态和市场来源分别控制不同环节，先写清组织想限制什么，再组合相应设置，检查结果是否真的覆盖了策略。

插件分发出去之后，还要管好敏感配置、运行数据和升级回滚，这部分见 能回滚的 Claude Code 插件升级流程。Skill 从个人到项目再到插件的递进，见 把太长的 SKILL.md 拆成几个文件。

打包这件事可以晚一点。配置在项目里稳定下来、第二个仓库开口要用的时候，再做成插件，团队装到的就是同一份已经验证过的内容。