创建 Claude Code 插件

• 还没有任何内容：按照创建您的第一个插件，然后在没有市场的情况下开发和测试和调试。
• .claude/ 下已有文件：完成一次第一个插件演练以了解布局，然后按照转换现有的 .claude/ 设置。

​

决定何时使用插件

• 文件的位置：在插件自己的目录（称为插件根目录）下，作为 skills/、agents/、hooks/hooks.json 和 .mcp.json。
• 它们的命名方式：插件技能和代理获得插件名称作为前缀，例如 /my-plugin:hello，因此两个插件可以各自提供一个 hello 技能而不会冲突。

​

创建您的第一个插件

mkdir -p my-first-plugin/.claude-plugin

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

mkdir -p my-first-plugin/skills/hello

---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

claude plugin validate ./my-first-plugin

claude --plugin-dir ./my-first-plugin

/my-first-plugin:hello

​

共享您的插件

• 直接发送给少数人：给他们插件的目录或其 .zip，无需发布任何内容。请参阅在没有市场的情况下共享插件。
• 在您自己的市场中列出它：团队成员添加您的市场一次并按名称安装插件，他们会收到您的更新。请参阅通过您自己的市场发布。
• 提交到 Anthropic 的社区市场：一旦列出，任何添加该市场的人都可以安装它。请参阅提交到社区市场。

​

插件布局

​

在没有市场的情况下开发

• --plugin-dir：为一个会话加载目录或 .zip 存档。
• --plugin-url：为一个会话从 URL 获取 .zip 存档。
• claude plugin init：在 ~/.claude/skills/ 下搭建一个插件，在每个会话中加载。

​

为一个会话加载插件

​

从目录或 .zip

claude --plugin-dir ./my-first-plugin --plugin-dir ./other-plugin.zip

​

从插件文件夹

• 您添加的子文件夹一旦其清单存在就作为新插件加载。
• 当您删除子文件夹时，其插件卸载。

​

从 URL

claude --plugin-url https://example.com/my-first-plugin.zip

​

从环境变量

​

使插件在每个会话中加载

​

使用 claude plugin init 搭建插件

claude plugin init my-tool

​

命名插件的技能

​

停止加载插件

​

通过存储库共享插件

​

测试和调试

1. 在您的 shell 中，运行 claude plugin validate <path>。它检查清单和每个技能、代理和命令文件的 frontmatter，并在 Validation passed 时退出 0。添加 --strict 也会在警告时失败。退出代码和目录处理在插件命令参考上。
2. 在运行的会话中，运行 /reload-plugins 以应用您在磁盘上所做的编辑。它打印一个 Reloaded: 行，其中包含计数。然后通过键入其 /plugin-name:skill 命令或在 /plugin 已安装选项卡中找到插件来确认技能已加载。
3. 在同一会话中，运行 /plugin。已安装选项卡列出您的插件，在插件的详细信息中，Claude Code 找到的组件。错误选项卡列出了什么未能加载以及原因，例如清单中不存在的路径。
4. 回到您的 shell，运行 claude plugin list。它在各自的部分中打印仅会话和技能目录插件，带有 Status: ✔ loaded 或加载错误。要包括您正在开发的插件，请在 plugin list 之前使用其路径传递 --plugin-dir。

​

找不到组件路径

​

--plugin-dir 在市场根目录不加载 plugins/ 下的插件

​

插件加载但其技能缺失

​

userConfig 对话框从不出现

​

检查插件是否改变了 Claude 的行为

​

转换现有的 .claude/ 设置

mkdir -p my-plugin/.claude-plugin

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

mkdir -p my-plugin/hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
      }
    ]
  }
}

claude --plugin-dir ./my-plugin

• 技能和代理：这两个集合不会冲突，因为插件的技能和代理带有 my-plugin: 前缀。/deploy 和 /my-plugin:deploy 都有效，Claude 将 reviewer 和 my-plugin:reviewer 视为两个子代理。
• Hooks：hooks 没有前缀，因此同时在您的设置文件和 hooks/hooks.json 中的 hook 在其事件每次触发时运行两次。

​

后续步骤

• 插件组件：向您的插件添加代理、hooks、MCP 服务器、LSP 服务器和用户配置
• 使用 evals 测试插件：编写 eval 用例并使用 claude plugin eval 运行它们以检查插件引导 Claude 行为的可靠性
• 发布插件：对其进行版本控制，将其放在市场中，并提交到社区市场
• claude.ai 和 Cowork 中的插件：同一插件文件夹在 claude.ai 和 Cowork 中安装。某些组件仅限 Claude Code
• 插件清单参考：每个 plugin.json 字段、路径规则和目录
• 技能：编写您的插件提供的技能
• Anthropic 在 claude-code 存储库中的插件：本页面布局的完整工作示例，例如 feature-dev 和 code-review