plugins.md +0 −527 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# 创建插件
6
7> 创建自定义插件以使用 skills、agents、hooks 和 MCP servers 扩展 Claude Code。
8
9Plugins 让你能够使用自定义功能扩展 Claude Code，这些功能可以在项目和团队中共享。本指南涵盖如何使用 skills、agents、hooks 和 MCP servers 创建自己的插件。
10
11想要安装现有插件？请参阅[发现和安装插件](/docs/zh-CN/discover-plugins)。有关完整的技术规范，请参阅[插件参考](/docs/zh-CN/plugins-reference)。
12
13<h2 id="when-to-use-plugins-vs-standalone-configuration">
14 何时使用插件与独立配置
15</h2>
16
17Claude Code 支持两种方式来添加自定义 skills、agents 和 hooks：
18
19| 方法 | Skill 名称 | 最适合 |
20| :--------------------------------------------------------------------- | :------------------- | :------------------------ |
21| **独立**（`.claude/` 目录） | `/hello` | 个人工作流、项目特定的自定义、快速实验 |
22| **插件**（包含 skills、agents、hooks 或 `.claude-plugin/plugin.json` 清单的自包含目录） | `/plugin-name:hello` | 与团队成员共享、分发到社区、版本化发布、跨项目重用 |
23
24<Tip>
25 从 `.claude/` 中的独立配置开始进行快速迭代，然后在准备好共享时[转换为插件](#convert-existing-configurations-to-plugins)。
26</Tip>
27
28<h2 id="quickstart">
29 快速开始
30</h2>
31
32本快速开始将引导你创建一个带有自定义 skill 的插件。你将创建一个清单（定义插件的配置文件）、添加一个 skill，并使用 `--plugin-dir` 标志在本地测试它。
33
34<h3 id="prerequisites">
35 前置条件
36</h3>
37
38* Claude Code [已安装并已认证](/docs/zh-CN/quickstart#step-1-install-claude-code)
39
40<h3 id="create-your-first-plugin">
41 创建你的第一个插件
42</h3>
43
44<Steps>
45 <Step title="创建插件目录">
46 每个插件都位于其自己的目录中，包含你的 skills、agents 或 hooks，可选地与 `.claude-plugin/plugin.json` 清单一起。该位置对于本快速开始并不重要，因为你将在测试步骤中使用 `--plugin-dir` 指向 Claude Code 该目录。在任何方便的地方创建它，例如临时文件夹或项目目录：
47
48 ```bash theme={null}
49 mkdir my-first-plugin
50 ```
51
52 其余步骤从父目录运行，并引用相对于它的路径，如 `my-first-plugin/...`。
53 </Step>
54
55 <Step title="创建插件清单">
56 位于 `.claude-plugin/plugin.json` 的清单文件定义了你的插件的身份：其名称、描述和版本。Claude Code 使用此元数据在插件管理器中显示你的插件。
57
58 在你的插件文件夹内创建 `.claude-plugin` 目录：
59
60 ```bash theme={null}
61 mkdir my-first-plugin/.claude-plugin
62 ```
63
64 然后使用以下内容创建 `my-first-plugin/.claude-plugin/plugin.json`：
65
66 ```json my-first-plugin/.claude-plugin/plugin.json theme={null}
67 {
68 "name": "my-first-plugin",
69 "description": "A greeting plugin to learn the basics",
70 "version": "1.0.0",
71 "author": {
72 "name": "Your Name"
73 }
74 }
75 ```
76
77 | 字段 | 目的 |
78 | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79 | `name` | 唯一标识符和 skill 命名空间。Skills 以此为前缀（例如 `/my-first-plugin:hello`）。 |
80 | `description` | 在浏览或安装插件时在插件管理器中显示。 |
81 | `version` | 可选。如果设置，用户仅在你更新此字段时接收更新，除了 [`command` 源](/docs/zh-CN/plugin-marketplaces#command-sources)或[就地加载](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)的插件；请参阅[版本管理](/docs/zh-CN/plugins-reference#version-management)。如果省略，版本来自[版本管理](/docs/zh-CN/plugins-reference#version-management)中的下一个源。 |
82 | `author` | 可选。有助于归属。 |
83
84 有关 `homepage`、`repository` 和 `license` 等其他字段，请参阅[完整清单架构](/docs/zh-CN/plugins-reference#plugin-manifest-schema)。
85 </Step>
86
87 <Step title="添加 skill">
88 Skills 位于 `skills/` 目录中。每个 skill 是一个包含 `SKILL.md` 文件的文件夹。文件夹名称成为 skill 名称，以插件的命名空间为前缀（在名为 `my-first-plugin` 的插件中的 `hello/` 创建 `/my-first-plugin:hello`）。
89
90 在你的插件文件夹中创建一个 skill 目录：
91
92 ```bash theme={null}
93 mkdir -p my-first-plugin/skills/hello
94 ```
95
96 然后使用以下内容创建 `my-first-plugin/skills/hello/SKILL.md`：
97
98 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}
99 ---
100 description: Greet the user with a friendly message
101 disable-model-invocation: true
102 ---
103
104 Greet the user warmly and ask how you can help them today.
105 ```
106 </Step>
107
108 <Step title="测试你的插件">
109 使用 `--plugin-dir` 标志运行 Claude Code 以加载你的插件：
110
111 ```bash theme={null}
112 claude --plugin-dir ./my-first-plugin
113 ```
114
115 Claude Code 启动后，尝试你的新 skill：
116
117 ```shell theme={null}
118 /my-first-plugin:hello
119 ```
120
121 你将看到 Claude 用问候语回应。运行 `/help` 并打开**自定义命令**选项卡以查看你的 skill 在插件命名空间下列出。
122
123 <Note>
124 **为什么要命名空间？** 插件 skills 总是命名空间化的（如 `/my-first-plugin:hello`），以防止多个插件具有相同名称的 skills 时发生冲突。
125
126 要更改命名空间前缀，请更新 `plugin.json` 中的 `name` 字段。
127 </Note>
128 </Step>
129
130 <Step title="添加 skill 参数">
131 通过接受用户输入使你的 skill 动态化。`$ARGUMENTS` 占位符捕获用户在 skill 名称后提供的任何文本。
132
133 更新你的 `SKILL.md` 文件：
134
135 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}
136 ---
137 description: Greet the user with a personalized message
138 ---
139
140 # Hello Skill
141
142 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
143 ```
144
145 运行 `/reload-plugins` 以获取更改。然后尝试使用你的名字的 skill：
146
147 ```shell theme={null}
148 /my-first-plugin:hello Alex
149 ```
150
151 Claude 将按名字问候你。有关向 skills 传递参数的更多信息，请参阅 [Skills](/docs/zh-CN/skills#pass-arguments-to-skills)。
152 </Step>
153</Steps>
154
155<Tip>
156 `--plugin-dir` 标志对开发和测试很有用。当你准备好与他人共享你的插件时，请参阅[创建和分发插件市场](/docs/zh-CN/plugin-marketplaces)。
157</Tip>
158
159<h2 id="develop-a-plugin-in-your-skills-directory">
160 在你的 skills 目录中开发插件
161</h2>
162
163与其在每次启动时传递 `--plugin-dir`，你可以在你的 skills 目录中保留一个插件，并让 Claude Code 自动加载它。`claude plugin init` 会为你搭建一个：
164
165```bash theme={null}
166claude plugin init my-tool
167```
168
169这会创建 `~/.claude/skills/my-tool/`，其中包含 `.claude-plugin/plugin.json` 清单和一个启动器 `SKILL.md`。在下一个会话中，它会作为 `my-tool@skills-dir` 加载，无需市场或安装步骤。
170
171有关自动加载规则、个人与项目范围、工作区信任要求以及如何更新或删除一个，请参阅 [Skills-directory plugins](/docs/zh-CN/plugins-reference#skills-directory-plugins)。
172
173<h2 id="plugin-structure-overview">
174 插件结构概览
175</h2>
176
177你已创建了一个带有 skill 的插件，但插件可以包含更多内容：自定义 agents、hooks、MCP servers、LSP servers 和后台监视器。
178
179<Warning>
180 **常见错误**：不要将 `commands/`、`agents/`、`skills/` 或 `hooks/` 放在 `.claude-plugin/` 目录内。只有 `plugin.json` 应该在 `.claude-plugin/` 内。所有其他目录必须在插件根级别。
181
182 插件根是单个插件自己的目录，例如来自[快速开始](#quickstart)的 `my-first-plugin/`。它永远不是 `~/.claude/`。例如，Claude Code 不会读取放在 `~/.claude/.mcp.json` 的 `.mcp.json`。
183</Warning>
184
185| 目录 | 位置 | 目的 |
186| :---------------- | :-- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
187| `.claude-plugin/` | 插件根 | 包含 `plugin.json` 清单（如果组件使用默认位置，则可选） |
188| `skills/` | 插件根 | Skills 作为 `<name>/SKILL.md` 目录 |
189| `commands/` | 插件根 | Skills 作为平面 Markdown 文件。为新插件使用 `skills/` |
190| `agents/` | 插件根 | 自定义 agent 定义 |
191| `hooks/` | 插件根 | `hooks.json` 中的事件处理程序 |
192| `.mcp.json` | 插件根 | MCP server 配置 |
193| `.lsp.json` | 插件根 | 用于代码智能的 LSP server 配置 |
194| `monitors/` | 插件根 | `monitors.json` 中的后台监视器配置 |
195| `bin/` | 插件根 | 在启用插件时添加到 Bash tool 的 `PATH` 的可执行文件。你不能在[通过 claude.ai 组织设置分发的插件中包含此目录](/docs/zh-CN/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory) |
196| `settings.json` | 插件根 | 启用插件时应用的默认[设置](/docs/zh-CN/settings) |
197
198恰好包含一个 skill 的插件可以直接在插件根目录放置 `SKILL.md`，而不是创建 `skills/` 目录。Claude Code 会将其作为单个 skill 加载，并使用 frontmatter 中的 `name` 字段作为调用名称。对于可能增长到多个 skill 的插件，请使用 `skills/` 布局。
199
200<h2 id="develop-more-complex-plugins">
201 开发更复杂的插件
202</h2>
203
204一旦你对基本插件感到满意，你可以创建更复杂的扩展。
205
206<h3 id="add-skills-to-your-plugin">
207 向你的插件添加 Skills
208</h3>
209
210插件可以包含 [Agent Skills](/docs/zh-CN/skills) 以扩展 Claude 的功能。Skills 是模型调用的：Claude 根据任务上下文自动使用它们。
211
212在你的插件根目录添加一个 `skills/` 目录，其中包含包含 `SKILL.md` 文件的 Skill 文件夹：
213
214```text theme={null}
215my-plugin/
216├── .claude-plugin/
217│ └── plugin.json
218└── skills/
219 └── code-review/
220 └── SKILL.md
221```
222
223每个 `SKILL.md` 包含 YAML frontmatter 和说明。包含一个 `description`，以便 Claude 知道何时使用该 skill：
224
225```yaml theme={null}
226description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
227
228When reviewing code, check for:
2291. Code organization and structure
2302. Error handling
2313. Security concerns
2324. Test coverage
233```
234
235安装插件后，检查安装摘要：如果它报告 `Run /reload-plugins to activate.`，请参阅 [Apply plugin changes without restarting](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting) 以在当前会话中加载 Skills。有关完整的 Skill 编写指南，包括渐进式披露和工具限制，请参阅 [Agent Skills](/docs/zh-CN/skills)。
236
237<h3 id="add-lsp-servers-to-your-plugin">
238 向你的插件添加 LSP servers
239</h3>
240
241<Tip>
242 对于 TypeScript、Python 和 Rust 等常见语言，请从官方市场安装预构建的 LSP 插件。仅当你需要支持尚未涵盖的语言时，才创建自定义 LSP 插件。
243</Tip>
244
245LSP（Language Server Protocol）插件为 Claude 提供实时代码智能。如果你需要支持没有官方 LSP 插件的语言，你可以通过向你的插件添加 `.lsp.json` 文件来创建自己的：
246
247```json .lsp.json theme={null}
248{
249 "go": {
250 "command": "gopls",
251 "args": ["serve"],
252 "extensionToLanguage": {
253 ".go": "go"
254 }
255 }
256}
257```
258
259安装你的插件的用户必须在其机器上安装语言服务器二进制文件。
260
261要确认服务器启动，使用启用的插件启动 Claude Code 并检查 `/plugin` Errors 标签：启动失败的语言服务器会出现在那里，例如当二进制文件未安装时显示 `Executable not found in $PATH`。具有无效配置的条目会被跳过；运行 `claude --debug` 以查看原因。
262
263有关完整的 LSP 配置选项，请参阅 [LSP servers](/docs/zh-CN/plugins-reference#lsp-servers)。
264
265<h3 id="add-background-monitors-to-your-plugin">
266 向你的插件添加后台监视器
267</h3>
268
269后台监视器让你的插件在后台监视日志、文件或外部状态，并在事件到达时通知 Claude。Claude Code 在插件处于活动状态时自动启动每个监视器，因此你无需指示 Claude 启动监视。
270
271在插件根目录添加一个 `monitors/monitors.json` 文件，其中包含监视器条目数组：
272
273```json monitors/monitors.json theme={null}
274[
275 {
276 "name": "error-log",
277 "command": "tail -F ./logs/error.log",
278 "description": "Application error log"
279 }
280]
281```
282
283来自 `command` 的每个 stdout 行在会话期间作为通知传递给 Claude。有关完整的架构，包括 `when` 触发器和变量替换，请参阅 [Monitors](/docs/zh-CN/plugins-reference#monitors)。
284
285<h3 id="ship-default-settings-with-your-plugin">
286 使用你的插件提供默认设置
287</h3>
288
289插件可以在插件根目录包含一个 `settings.json` 文件，以在启用插件时应用默认配置。目前仅支持 `agent` 和 `subagentStatusLine` 键。
290
291设置 `agent` 激活插件的[自定义 agents](/docs/zh-CN/sub-agents) 之一作为主线程，应用其系统提示、工具限制和模型。这让插件在启用时通过改变 Claude Code 的默认行为方式。
292
293```json settings.json theme={null}
294{
295 "agent": "security-reviewer"
296}
297```
298
299此示例激活在插件的 `agents/` 目录中定义的 `security-reviewer` agent。来自 `settings.json` 的设置优先于在 `plugin.json` 中声明的 `settings`。未知键被静默忽略。
300
301<h3 id="organize-complex-plugins">
302 组织复杂的插件
303</h3>
304
305对于具有许多组件的插件，按功能组织你的目录结构。有关完整的目录布局和组织模式，请参阅 [Plugin directory structure](/docs/zh-CN/plugins-reference#plugin-directory-structure)。
306
307<h3 id="test-your-plugins-locally">
308 在本地测试你的插件
309</h3>
310
311使用 `--plugin-dir` 标志在开发期间测试插件。这会直接加载你的插件，无需安装。
312
313```bash theme={null}
314claude --plugin-dir ./my-plugin
315```
316
317该标志也接受插件目录的 `.zip` 存档。
318
319```bash theme={null}
320claude --plugin-dir ./my-plugin.zip
321```
322
323当 `--plugin-dir` 插件与已安装的市场插件同名时，本地副本在该会话中优先。这让你可以测试已安装的插件的更改，而无需先卸载它。由托管设置强制启用或强制禁用的插件是唯一的例外：`--plugin-dir` 无法覆盖这些。
324
325当你对插件进行更改时，运行 `/reload-plugins` 以获取更新，无需重新启动。这会重新加载 plugins、skills、agents、hooks、插件 MCP servers 和插件 LSP servers；在没有交互式终端的会话中，插件 MCP server 更改[等待你的下一个会话](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting)。测试你的插件组件：
326
327* 使用 `/plugin-name:skill-name` 尝试你的 skills
328* 检查 agents 是否出现在 `/context` 中的 Custom Agents 下，或通过其作用域名称 @-mention 其中一个
329* 触发每个 hook 匹配的事件，例如要求 Claude 编辑文件以进行 `PostToolUse` hook，并确认其效果。Claude Code 在[调试日志](/docs/zh-CN/hooks#debug-hooks)中记录哪些 hooks 匹配、它们的退出代码和它们的输出
330
331<Tip>
332 你可以通过多次指定标志来一次加载多个插件：
333
334 ```bash theme={null}
335 claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
336 ```
337
338 要测试一个插件及其依赖的插件，请参阅 [Test a plugin and its dependency locally](/docs/zh-CN/plugin-dependencies#test-a-plugin-and-its-dependency-locally)。
339</Tip>
340
341要在无法添加标志的会话中加载插件，请改为在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-CN/env-vars#variables) 环境变量中列出它们的绝对路径。Claude Code 加载每个路径的方式与加载 `--plugin-dir` 路径的方式相同。这些插件除了你使用 `--plugin-dir` 传递的任何插件外，还会加载。[项目和本地设置无法设置此变量](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)。`CLAUDE_CODE_PLUGIN_DIRS` 需要 Claude Code v2.1.280 或更高版本。
342
343使用 `--plugin-dir` 尝试插件会告诉你它可以工作。要找出 Claude 实际上多久会使用它一次并获得正确的结果，请使用 [`claude plugin eval`](/docs/zh-CN/plugin-evals) 针对一组测试提示运行它。每个提示会在加载和不加载插件的情况下运行多次，因此你可以看到插件的贡献并在你更改它或新模型发布时捕获回归。
344
345要从一个地方加载多个插件，请传递一个包含它们的文件夹，例如 `--plugin-dir ./plugins`。加载一个插件文件夹需要 Claude Code v2.1.265 或更高版本。Claude Code 读取文件夹的顶级以决定哪些插件加载，在交互式会话中，它也会监视文件夹以查找后续更改：
346
347* **加载的内容**：如果文件夹的顶级没有清单或插件组件，Claude Code 会将其视为插件文件夹。每个具有 `.claude-plugin/plugin.json` 清单的直接子文件夹作为单独的插件加载。Claude Code 跳过文件夹中的所有其他内容而不报告错误，包括没有清单的插件。
348* **交互式会话期间的更改**：你添加的子文件夹在其清单就位后作为新插件加载，当你删除子文件夹时，其插件卸载。Claude Code 为每个更改在会话中打印一行。如果在对话中间应用更改会[使提示缓存失效](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)，Claude Code 会保留它，该行说要运行 `/reload-plugins` 以应用它。
349
350要测试已打包为 `.zip` 存档并托管在 URL 上的插件（例如 CI 构建工件），请改用 `--plugin-url`。Claude Code 在启动时获取存档并仅为该会话加载它。如果 Claude Code 无法获取存档或存档无效，它会在没有插件的情况下启动并记录一个插件加载错误，你可以在 `/plugin` 管理器的 **Errors** 标签中查看。与任何插件源相同的[信任考虑](/docs/zh-CN/discover-plugins#security)适用：仅将此标志指向你控制或信任的存档。
351
352要加载多个插件，请为每个 URL 重复该标志：
353
354```bash theme={null}
355claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip
356```
357
358或将空格分隔的 URL 作为一个带引号的参数传递：
359
360```bash theme={null}
361claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"
362```
363
364<h3 id="debug-plugin-issues">
365 调试插件问题
366</h3>
367
368如果你的插件不按预期工作：
369
3701. **检查结构**：确保你的目录在插件根目录，而不是在 `.claude-plugin/` 内
3712. **单独测试组件**：分别检查每个 skill、agent 和 hook
3723. **使用验证和调试工具**：有关 CLI 命令和故障排除技术，请参阅 [Debugging and development tools](/docs/zh-CN/plugins-reference#debugging-and-development-tools)
373
374<h3 id="share-your-plugins">
375 共享你的插件
376</h3>
377
378当你的插件准备好共享时：
379
3801. **添加文档**：包含一个 `README.md`，其中包含安装和使用说明
3812. **选择版本控制策略**：决定是设置显式 `version` 还是依赖 [version management](/docs/zh-CN/plugins-reference#version-management) 中描述的回退。
3823. **创建或使用市场**：通过 [plugin marketplaces](/docs/zh-CN/plugin-marketplaces) 分发以供安装
3834. **与他人测试**：在更广泛分发之前让团队成员测试插件
384
385一旦你的插件在市场中，其他人可以使用 [Discover and install plugins](/docs/zh-CN/discover-plugins) 中的说明安装它。要将插件保持在你的团队内部，请在 [private repository](/docs/zh-CN/plugin-marketplaces#private-repositories) 中托管市场。
386
387<h3 id="submit-your-plugin-to-the-community-marketplace">
388 向社区市场提交你的插件
389</h3>
390
391Anthropic 为 Claude Code 插件维护两个公共市场：
392
393* **`claude-plugins-official`**：由 Anthropic 维护的精选插件集。在你首次以交互方式启动 Claude Code 时自动注册。如果你在该首次交互启动之前运行 Claude Code 非交互式，或[市场政策](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions)阻止了早期尝试，请使用 `claude plugin marketplace add anthropics/claude-plugins-official` 自己注册。
394* **`claude-community`**：公共社区市场，第三方提交在审查后进入。用户使用 `/plugin marketplace add anthropics/claude-plugins-community` 添加它，并从中安装为 `@claude-community`。
395
396要提交你的插件以供社区市场审查，请使用以下应用内表单之一：
397
398* **claude.ai**：[claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)
399* **Console**：[platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)
400
401claude.ai 表单需要 Team 或 Enterprise 组织和目录管理访问权限；组织所有者默认具有此访问权限。不属于 Team 或 Enterprise 组织的个人作者可以改用 Console 表单。
402
403在提交之前，在本地运行 `claude plugin validate ./your-plugin`，将 `./your-plugin` 替换为你的插件目录的路径。审查管道对每个提交运行相同的检查，以及自动安全筛选。当验证通过时，Claude Code 打印 `✔ Validation passed`，或如果有警告则打印 `✔ Validation passed with warnings`。警告不会导致验证失败；添加 `--strict` 以将它们视为错误。
404
405批准的插件被固定到 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 目录中的特定提交 SHA，当你向你的存储库推送新提交时，CI 会自动提升该固定。公共目录每晚从审查管道同步，因此批准和你的插件出现在 `marketplace.json` 中之间可能会有延迟。要检查你的插件是否已可安装，请在[社区目录](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)中搜索其名称。
406
407官方市场 `claude-plugins-official` 是单独策划的。Anthropic 自行决定包含哪些插件。没有申请流程，提交表单不会将插件添加到官方市场。
408
409如果 Anthropic 在官方市场中列出你的插件，你的 CLI 可以提示 Claude Code 用户安装它。请参阅 [Recommend your plugin from your CLI](/docs/zh-CN/plugin-hints)。
410
411<h2 id="convert-existing-configurations-to-plugins">
412 将现有配置转换为插件
413</h2>
414
415如果你已经在 `.claude/` 目录中有 skills 或 hooks，你可以将它们转换为插件，以便更轻松地共享和分发。
416
417<h3 id="migration-steps">
418 迁移步骤
419</h3>
420
421<Steps>
422 <Step title="创建插件结构">
423 在你的项目根目录中创建一个新的插件目录，与现有的 `.claude/` 文件夹并排放置，以便下一步中的相对 `cp` 路径能够解析：
424
425 ```bash theme={null}
426 mkdir -p my-plugin/.claude-plugin
427 ```
428
429 在 `my-plugin/.claude-plugin/plugin.json` 处创建清单文件：
430
431 ```json my-plugin/.claude-plugin/plugin.json theme={null}
432 {
433 "name": "my-plugin",
434 "description": "Migrated from standalone configuration",
435 "version": "1.0.0"
436 }
437 ```
438 </Step>
439
440 <Step title="复制你现有的文件">
441 将你拥有的每个配置目录复制到插件根目录。你可能没有全部三个：如果一个目录不存在，`cp` 会打印 `No such file or directory` 并且不复制任何内容，所以跳过该命令或忽略错误。
442
443 ```bash theme={null}
444 cp -r .claude/commands my-plugin/
445
446 cp -r .claude/agents my-plugin/
447
448 cp -r .claude/skills my-plugin/
449 ```
450
451 你的插件现在包含了你在 `.claude/` 下拥有的目录的副本。运行 `ls my-plugin` 来确认：你应该看到你复制的每个目录。
452 </Step>
453
454 <Step title="迁移 hooks">
455 如果你在设置中有 hooks，请创建一个 hooks 目录：
456
457 ```bash theme={null}
458 mkdir my-plugin/hooks
459 ```
460
461 使用你的 hooks 配置创建 `my-plugin/hooks/hooks.json`。从你的 `.claude/settings.json` 或 `settings.local.json` 复制 `hooks` 对象，因为格式相同。命令在 stdin 上接收 hook 输入作为 JSON，所以使用 `jq` 提取文件路径：
462
463 ```json my-plugin/hooks/hooks.json theme={null}
464 {
465 "hooks": {
466 "PostToolUse": [
467 {
468 "matcher": "Write|Edit",
469 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
470 }
471 ]
472 }
473 }
474 ```
475 </Step>
476
477 <Step title="测试你迁移的插件">
478 加载你的插件以验证一切正常：
479
480 ```bash theme={null}
481 claude --plugin-dir ./my-plugin
482 ```
483
484 测试每个组件：运行你的命令、检查 agents 是否出现在 `/context` 中，并触发每个 hook 匹配的事件以确认其效果。Claude Code 在[调试日志](/docs/zh-CN/hooks#debug-hooks)中记录了哪些 hooks 匹配以及它们如何退出。
485 </Step>
486</Steps>
487
488<h3 id="what-changes-when-migrating">
489 迁移时的变化
490</h3>
491
492| 独立（`.claude/`） | 插件 |
493| :----------------------- | :--------------------------- |
494| 仅在一个项目中可用 | 可以通过市场共享 |
495| `.claude/commands/` 中的文件 | `plugin-name/commands/` 中的文件 |
496| `settings.json` 中的 Hooks | `hooks/hooks.json` 中的 Hooks |
497| 必须手动复制以共享 | 使用 `/plugin install` 安装 |
498
499<Note>
500 迁移后，从 `.claude/` 中删除原始文件以避免重复。项目和用户 `.claude/agents/` 定义会覆盖同名的插件 agents，因此插件版本仅在删除原始文件后才会生效。Plugin skills 被命名为 `/plugin-name:skill-name`，所以原始的 `/skill-name` 和插件副本都保持可用，而不是其中一个覆盖另一个。
501</Note>
502
503<h2 id="next-steps">
504 后续步骤
505</h2>
506
507现在你了解了 Claude Code 的插件系统，以下是针对不同目标的建议路径：
508
509<h3 id="for-plugin-users">
510 对于插件用户
511</h3>
512
513* [发现和安装插件](/docs/zh-CN/discover-plugins)：浏览市场并安装插件
514* [配置团队市场](/docs/zh-CN/discover-plugins#configure-team-marketplaces)：为你的团队设置存储库级别的插件
515
516<h3 id="for-plugin-developers">
517 对于插件开发者
518</h3>
519
520* [使用 evals 测试插件](/docs/zh-CN/plugin-evals)：测量你的插件改变了什么并在 CI 中进行门控
521* [创建和分发市场](/docs/zh-CN/plugin-marketplaces)：打包和共享你的插件
522* [插件参考](/docs/zh-CN/plugins-reference)：完整的技术规范
523* 深入了解特定的插件组件：
524 * [Skills](/docs/zh-CN/skills)：skill 开发详情
525 * [Subagents](/docs/zh-CN/sub-agents)：agent 配置和功能
526 * [Hooks](/docs/zh-CN/hooks)：事件处理和自动化
527 * [MCP](/docs/zh-CN/mcp)：外部工具集成