向插件添加组件

​

浏览插件目录

• 一个审查 skill 和一个 about 命令
• 一个 security-review 子代理
• 一个在 Claude 编辑文件后格式化文件的 hook，以及它调用的 scripts/ 文件夹
• 一个日志监视器
• 一个输出样式和一个颜色主题
• 一个 route-audit 工作流
• 一个 hello-plugin 可执行文件
• 默认设置
• 一个本地 MCP 服务器和一个 Go 语言服务器

​

添加每种组件

​

Skills

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

• 命令名称：/<plugin>:<directory>，所以 my-plugin 中的 skills/review/SKILL.md 是 /my-plugin:review。如果您在 frontmatter 中设置 name，它替换最后一段，插件前缀保持不变。请参阅skill 如何获得其命令名称
• 谁调用它：Claude、用户或两者，由 frontmatter 控制。请参阅控制谁调用 skill

• 其他目录：在 skills 清单键中列出它们。它们添加到默认 skills/ 扫描，而不是替换它，不像 commands 和 agents
• 插件根目录中的单个 skill：没有 skills/ 目录且没有 skills 清单键，插件根目录中的 SKILL.md 加载为一个 skill。在其 frontmatter 中设置 name，因为否则市场安装会根据其缓存目录而不是您的插件命名 skill

​

命令

​

在清单中定义命令

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

Agents

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

​

在子文件夹中组织 agents

• Frontmatter name：它仅替换文件名，所以 agents/review/security.md 中的 name: audit 加载为 my-plugin:review:audit
• 清单 agents 字段：您在那里列出的文件加载时不带子文件夹名称，所以 "agents": "./custom/review/security.md" 加载为 my-plugin:security

​

插件 agents 中的 Frontmatter 字段

• 支持的字段：name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background、omitClaudeMd、isolation、color 和 experimental 的 cacheTtl 键。唯一有效的 isolation 值是 "worktree"。请参阅支持的 frontmatter 字段了解每个字段的作用
• 忽略的字段：permissionMode、hooks、mcpServers 和 initialPrompt。agent 文件不能自己添加 hooks 或 MCP 服务器，所以改为添加这些作为插件 hooks 和 MCP 服务器
• 不解析的 Frontmatter：agent 仍然加载，每个字段都被忽略。它根据文件命名，其描述读作 Agent from my-plugin plugin。在 shell 中运行 claude plugin validate 来找到这些文件

​

Hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

​

插件 hooks 何时触发

​

环境、引用和匹配 MCP 工具

• 环境：每个 hook 进程在其环境中接收 CLAUDE_PLUGIN_ROOT 和 CLAUDE_PLUGIN_DATA，加上每个用户配置值的 CLAUDE_PLUGIN_OPTION_<KEY>，所以您的脚本可以从那里读取它们
• 引用：当 command 没有 args 时，它通过 shell 运行，所以用双引号包装 ${CLAUDE_PLUGIN_ROOT} 路径，如 Hooks 下的 hooks/hooks.json 示例所做的那样，以保持扩展的路径为一个 shell 单词。当您改为传递 args 时，每个元素作为一个参数传递，没有 shell，不需要引用。请参阅 exec 形式和 shell 形式
• 匹配插件自己的 MCP 工具：来自此插件声明的 MCP 服务器的工具被命名为 mcp__plugin_<plugin>_<server>__<tool>，所以在匹配器中写那个完整名称。仅在服务器名称上的匹配器从不触发。请参阅匹配 MCP 工具

​

MCP 服务器

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

到达 claude.ai 和 Cowork 中的用户

​

服务器名称、工具名称和重新加载

• 服务器名称：plugin:<plugin>:<server>，所以 my-plugin 中的 db 服务器在 /mcp 中是 plugin:my-plugin:db。使用相同的形式在 mcp_tool hook 中命名服务器
• 工具名称：mcp__plugin_<plugin>_<server>__<tool>，所以该 db 服务器上的 query 工具是 mcp__plugin_my-plugin_db__query。这是在权限规则和 hook 匹配器中使用的名称
• 替换：${CLAUDE_PLUGIN_ROOT} 和其他路径变量在 command、args 和 env 中被替换。args 中不需要引用，因为每个元素作为一个参数传递
• 重新加载：当用户运行 /reload-plugins 并且重新加载应用时，配置未改变的服务器保持其连接。配置改变的服务器重新连接，您删除的服务器断开连接

​

包含打包的 MCPB 服务器

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

​

LSP 服务器

{
  "gopls": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

• 缺少二进制：Claude Code 从用户的 PATH 按名称启动 command。当二进制不存在时，服务器启动失败，claude --debug 记录 LSP server <name> failed to start
• 扩展冲突：当两个启用的服务器声称相同的扩展名时，首先注册的处理这些文件，另一个不用于它们，无论服务器来自一个插件还是两个。/plugin Errors 标签显示警告 LSP server "<name>" is not used for <ext> files

​

可执行文件

#!/bin/bash
echo "hello from my-plugin"

​

默认设置

{
  "agent": "security-reviewer"
}

• 文件优于清单：当两者都存在且 settings.json 设置至少一个支持的键时，settings.json 应用，清单的 settings 被忽略
• 用户设置优于插件默认值：跨设置源，插件默认值是最低层，所以用户自己在 ~/.claude/settings.json 中的 agent 覆盖您的
• 两个插件设置相同的键：最后加载的插件的值应用，claude --debug 记录 overrides setting

​

主题和输出样式

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

​

频道

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

​

监视器

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

• 仅交互式会话：插件监视器在交互式会话中启动，从不在带 -p 标志的非交互式模式中。它们也仅在 Monitor 工具可用的地方启动
• 无用户配置：command 获取路径变量和环境中的 ${ENV_VAR}，但从不获取 ${user_config.*}。引用一个的监视器不启动，监视器进程也不接收 CLAUDE_PLUGIN_OPTION_<KEY>
• 中途禁用：如果您在会话中途禁用插件，Claude Code 不停止已经运行的监视器。它们在会话结束时停止

​

要求用户提供配置值

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

​

配置对话框何时出现

• 在 /plugin 中安装插件
• 在会话内运行 /plugin install <plugin>@<marketplace>
• 从 /plugin 中的 Installed 标签启用插件

​

引用插件路径和存储数据

• ${CLAUDE_PLUGIN_ROOT}：插件的安装目录。每个版本都有自己的缓存目录，所以当插件更新时路径改变。不要在那里写状态
• ${CLAUDE_PLUGIN_DATA}：一个在更新中存活的目录，用于 node_modules、虚拟环境和缓存。它解析为 ~/.claude/plugins/data/<id>/ 并在首次引用时创建
• ${CLAUDE_PROJECT_DIR}：项目根目录，hooks 接收的相同值

​

将依赖项安装到数据目录

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

​

后续步骤

• 插件清单参考：plugin.json 字段、路径规则和标准布局
• 使用 evals 测试插件：检查您添加的组件以您打算的方式改变 Claude 的行为
• 发布和分发插件：版本化插件并将其放在市场中
• 排查插件问题：当组件不加载或 hook 不触发时该怎么办