新增元件至外掛程式

​

探索外掛程式目錄

• 一個審查 skill 和一個 about 命令
• 一個安全審查子代理
• 一個在 Claude 編輯檔案後格式化檔案的 hook，以及它呼叫的 scripts/ 資料夾
• 一個日誌監視器
• 一個輸出樣式和一個色彩主題
• 一個路由審計工作流程
• 一個 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 manifest 鍵中列出它們。它們新增至預設 skills/ 掃描，而不是取代它，不像 commands 和 agents
• 外掛程式根目錄的單一 skill：沒有 skills/ 目錄且沒有 skills manifest 鍵，外掛程式根目錄的 SKILL.md 載入為一個 skill。在其 frontmatter 中設定 name，因為否則市場安裝會在其 快取目錄 之後命名 skill，而不是您的外掛程式

​

命令

​

在 manifest 中定義命令

{
  "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
• Manifest 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"
}

• 檔案優於 manifest：當兩者都存在且 settings.json 設定至少一個支援的鍵時，settings.json 適用，manifest 的 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\""
          }
        ]
      }
    ]
  }
}

​

後續步驟

• 外掛程式 manifest 參考：plugin.json 欄位、路徑規則和標準配置
• 使用 evals 測試外掛程式：檢查您新增的元件以您的意圖改變 Claude 的行為
• 發佈和分發外掛程式：版本化外掛程式並將其放在市場中
• 疑難排解外掛程式：當元件無法載入或 hook 無法觸發時該怎麼辦