建立 plugins

建立自訂 plugins 以使用 skills、agents、hooks 和 MCP servers 擴展 Claude Code。

Plugins 讓您使用可在專案和團隊中共享的自訂功能來擴展 Claude Code。本指南涵蓋使用 skills、agents、hooks 和 MCP servers 建立您自己的 plugins。

想要安裝現有的 plugins？請參閱探索和安裝 plugins。如需完整的技術規格，請參閱 Plugins 參考。

何時使用 plugins 與獨立配置

Claude Code 支援兩種方式來新增自訂 skills、agents 和 hooks：

快速入門

本快速入門將引導您建立具有自訂 skill 的 plugin。您將建立一個清單（定義您的 plugin 的配置檔案）、新增一個 skill，並使用 --plugin-dir 旗標在本地進行測試。

先決條件

• Claude Code 已安裝並驗證

建立您的第一個 plugin

mkdir my-first-plugin

mkdir 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

---
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-dir ./my-first-plugin

/my-first-plugin:hello

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

/my-first-plugin:hello Alex

在您的 skills 目錄中開發 plugin

與其在每次啟動時傳遞 --plugin-dir，您可以在您的 skills 目錄中保留一個 plugin，並讓 Claude Code 自動載入它。claude plugin init 會為您建立一個：

claude plugin init my-tool

這會建立 ~/.claude/skills/my-tool/，其中包含 .claude-plugin/plugin.json 清單和一個入門 SKILL.md。在下一個工作階段中，它會以 my-tool@skills-dir 的形式載入，無需市場或安裝步驟。

如需自動載入規則、個人與專案範圍、工作區信任要求，以及如何更新或移除一個，請參閱 Skills-directory plugins。

Plugin 結構概述

您已建立了具有 skill 的 plugin，但 plugins 可以包含更多內容：自訂 agents、hooks、MCP servers、LSP servers 和背景監視器。

只要 plugin 恰好包含一個 skill，就可以直接在 plugin 根目錄放置 SKILL.md，而不需要建立 skills/ 目錄。Claude Code 會將其載入為單一 skill，並使用 frontmatter 的 name 欄位作為叫用名稱。對於可能成長為多個 skill 的 plugins，請使用 skills/ 配置。

開發更複雜的外掛程式

一旦您熟悉了基本外掛程式，您可以建立更複雜的擴充功能。

將 Skills 新增至您的外掛程式

外掛程式可以包含 Agent Skills 來擴展 Claude 的功能。Skills 是由模型呼叫的：Claude 會根據任務背景自動使用它們。

在您的外掛程式根目錄新增一個 skills/ 目錄，其中包含包含 SKILL.md 檔案的 Skill 資料夾：

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

每個 SKILL.md 包含 YAML frontmatter 和說明。包含一個 description，以便 Claude 知道何時使用該 skill：

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

安裝外掛程式後，檢查安裝摘要：如果它報告 Run /reload-plugins to activate.，請參閱 Apply plugin changes without restarting 以在您目前的工作階段中載入 Skills。如需完整的 Skill 編寫指南（包括漸進式揭露和工具限制），請參閱 Agent Skills。

將 LSP 伺服器新增至您的外掛程式

LSP（Language Server Protocol）外掛程式為 Claude 提供即時程式碼智慧。如果您需要支援沒有官方 LSP 外掛程式的語言，您可以透過將 .lsp.json 檔案新增至您的外掛程式來建立自己的：

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

安裝您外掛程式的使用者必須在其機器上安裝語言伺服器二進位檔。

若要確認伺服器啟動，請啟動啟用外掛程式的 Claude Code 並檢查 /plugin 錯誤標籤：無法啟動的語言伺服器會出現在那裡，例如當二進位檔未安裝時出現 Executable not found in $PATH。具有無效設定的項目會被跳過；執行 claude --debug 以查看原因。

如需完整的 LSP 設定選項，請參閱 LSP servers。

將背景監視器新增至您的外掛程式

背景監視器讓您的外掛程式在背景中監視日誌、檔案或外部狀態，並在事件到達時通知 Claude。Claude Code 在外掛程式啟用時自動啟動每個監視器，因此您不需要指示 Claude 啟動監視。

在外掛程式根目錄新增一個 monitors/monitors.json 檔案，其中包含監視器項目的陣列：

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

來自 command 的每個 stdout 行都會在工作階段期間作為通知傳遞給 Claude。如需完整的結構描述（包括 when 觸發器和變數替換），請參閱 Monitors。

使用您的外掛程式提供預設設定

外掛程式可以在外掛程式根目錄包含一個 settings.json 檔案，以在啟用外掛程式時套用預設設定。目前僅支援 agent 和 subagentStatusLine 鍵。

設定 agent 會啟用外掛程式的其中一個 custom agents 作為主執行緒，套用其系統提示、工具限制和模型。這讓外掛程式在啟用時預設改變 Claude Code 的行為方式。

{
  "agent": "security-reviewer"
}

此範例啟用在外掛程式的 agents/ 目錄中定義的 security-reviewer 代理。來自 settings.json 的設定優先於在 plugin.json 中宣告的 settings。未知的鍵會被無聲地忽略。

組織複雜的外掛程式

對於具有許多元件的外掛程式，請按功能組織您的目錄結構。如需完整的目錄配置和組織模式，請參閱 Plugin directory structure。

在本機測試您的外掛程式

使用 --plugin-dir 旗標在開發期間測試外掛程式。這會直接載入您的外掛程式，無需安裝。

claude --plugin-dir ./my-plugin

該旗標也接受外掛程式目錄的 .zip 封存。

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

當 --plugin-dir 外掛程式的名稱與已安裝的市集外掛程式相同時，本機副本在該工作階段中優先。這讓您可以測試已安裝的外掛程式的變更，而無需先卸載它。例外是受管設定強制啟用或強制停用的外掛程式：--plugin-dir 無法覆蓋這些。

當您對外掛程式進行變更時，執行 /reload-plugins 以在不重新啟動的情況下取得更新。這會重新載入外掛程式、skills、代理、hooks、外掛程式 MCP 伺服器和外掛程式 LSP 伺服器；在沒有互動式終端的工作階段中，外掛程式 MCP 伺服器變更 等待您的下一個工作階段。測試您的外掛程式元件：

• 使用 /plugin-name:skill-name 嘗試您的 skills
• 檢查代理是否出現在 /context 下的 Custom Agents 中，或透過其範圍名稱 @-提及一個
• 觸發每個 hook 匹配的事件，例如要求 Claude 編輯檔案以進行 PostToolUse hook，並確認其效果。Claude Code 會記錄哪些 hooks 匹配、其結束代碼和其輸出在 debug log 中

若要在無法新增旗標的工作階段中載入外掛程式，請改為在 CLAUDE_CODE_PLUGIN_DIRS 環境變數中列出其絕對路徑。Claude Code 會將每個路徑載入為載入 --plugin-dir 路徑的方式。這些外掛程式會在您使用 --plugin-dir 傳遞的任何外掛程式之外載入。專案和本機設定無法設定此變數。CLAUDE_CODE_PLUGIN_DIRS 需要 Claude Code v2.1.280 或更新版本。

使用 --plugin-dir 嘗試外掛程式可以告訴您它是否能夠運作。若要找出 Claude 實際上多常使用它並獲得正確的結果，請使用 claude plugin eval 針對一組測試提示執行它。每個提示會在載入和不載入外掛程式的情況下執行多次，因此您可以看到外掛程式的貢獻，並在您變更它或新模型發佈時捕捉迴歸。

若要從一個位置載入多個外掛程式，請傳遞包含它們的資料夾，例如 --plugin-dir ./plugins。載入外掛程式資料夾需要 Claude Code v2.1.265 或更新版本。Claude Code 讀取資料夾的頂層以決定哪些外掛程式載入，在互動式工作階段中，它也會監視資料夾以進行後續變更：

• 載入的內容：如果資料夾的頂層沒有資訊清單或外掛程式元件，Claude Code 會將其視為外掛程式資料夾。每個具有 .claude-plugin/plugin.json 資訊清單的直接子資料夾都會作為單獨的外掛程式載入。Claude Code 會跳過資料夾中的所有其他內容，而不報告錯誤，包括沒有資訊清單的外掛程式。
• 互動式工作階段期間的變更：您新增的子資料夾在其資訊清單就位後會作為新外掛程式載入，當您移除子資料夾時，其外掛程式會卸載。Claude Code 會為每個變更在工作階段中列印一行。如果在對話中途套用變更會 使提示快取失效，Claude Code 會保留它，該行會說執行 /reload-plugins 以套用它。

若要測試已封裝為 .zip 封存並託管在 URL 上的外掛程式（例如 CI 建置成品），請改用 --plugin-url。Claude Code 在啟動時擷取封存並僅為該工作階段載入它。如果 Claude Code 無法擷取封存或封存無效，它會在沒有外掛程式的情況下啟動，並記錄您可以在 /plugin 管理員的 Errors 標籤中檢閱的外掛程式載入錯誤。與任何外掛程式來源相同的 trust considerations 適用：只將此旗標指向您控制或信任的封存。

若要載入多個外掛程式，請為每個 URL 重複該旗標：

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

或將空格分隔的 URL 作為一個引用的引數傳遞：

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

偵錯外掛程式問題

如果您的外掛程式未如預期運作：

1. 檢查結構：確保您的目錄位於外掛程式根目錄，而不是在 .claude-plugin/ 內
2. 個別測試元件：分別檢查每個 skill、代理和 hook
3. 使用驗證和偵錯工具：請參閱 Debugging and development tools 以取得 CLI 命令和疑難排解技術

分享您的外掛程式

當您的外掛程式準備好分享時：

1. 新增文件：包含一個 README.md，其中包含安裝和使用說明
2. 選擇版本控制策略：決定是否設定明確的 version 或依賴 version management 中描述的後備。
3. 建立或使用市集：透過 plugin marketplaces 進行分發以進行安裝
4. 與他人測試：在更廣泛的分發之前，讓團隊成員測試外掛程式

一旦您的外掛程式在市集中，其他人可以使用 Discover and install plugins 中的說明安裝它。若要將外掛程式保持在您的團隊內部，請在 private repository 中託管市集。

將您的外掛程式提交至社群市集

Anthropic 為 Claude Code 外掛程式維護兩個公開市集：

• claude-plugins-official：由 Anthropic 維護的精選外掛程式集。Claude Code 在您第一次以互動方式啟動 Claude Code 時自動註冊它。如果您在該首次互動啟動之前以非互動方式執行 Claude Code，或 marketplace policy 阻止了較早的嘗試，請使用 claude plugin marketplace add anthropics/claude-plugins-official 自行註冊。
• claude-community：公開社群市集，第三方提交在審查後會進入該市集。使用者使用 /plugin marketplace add anthropics/claude-plugins-community 新增它，並將其安裝為 @claude-community。

若要提交您的外掛程式以進行社群市集審查，請使用其中一個應用程式內表單：

• claude.ai：claude.ai/admin-settings/directory/submissions/plugins/new
• Console：platform.claude.com/plugins/submit

claude.ai 表單需要 Team 或 Enterprise 組織和目錄管理存取權；組織擁有者預設具有此存取權。不屬於 Team 或 Enterprise 組織的個別作者可以改用 Console 表單。

在提交之前，在本機執行 claude plugin validate ./your-plugin，將 ./your-plugin 替換為您的外掛程式目錄的路徑。審查管道對每個提交執行相同的檢查，以及自動安全篩選。驗證通過時，Claude Code 會列印 ✔ Validation passed，或如果有警告，則列印 ✔ Validation passed with warnings。警告不會導致驗證失敗；新增 --strict 以將它們視為錯誤。

已核准的外掛程式會固定到 anthropics/claude-plugins-community 目錄中的特定提交 SHA，CI 會在您推送新提交至您的儲存庫時自動提升該固定。公開目錄每晚從審查管道同步，因此核准和您的外掛程式出現在 marketplace.json 之間可能會有延遲。若要檢查您的外掛程式是否已可安裝，請在 community catalog 中搜尋其名稱。

官方市集 claude-plugins-official 是單獨精選的。Anthropic 自行決定要包含哪些外掛程式。沒有申請流程，提交表單不會將外掛程式新增至官方市集。

如果 Anthropic 在官方市集中列出您的外掛程式，您的 CLI 可以提示 Claude Code 使用者安裝它。請參閱 Recommend your plugin from your CLI。

將現有配置轉換為 plugins

如果您已經在 .claude/ 目錄中有 skills 或 hooks，您可以將它們轉換為 plugin，以便更輕鬆地共享和分發。

遷移步驟

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 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

遷移時的變更

後續步驟

現在您已了解 Claude Code 的 plugin 系統，以下是針對不同目標的建議路徑：

對於 plugin 使用者

• 探索和安裝 plugins：瀏覽市場並安裝 plugins
• 配置團隊市場：為您的團隊設定儲存庫級別的 plugins

對於 plugin 開發人員

• 使用 evals 測試 plugins：測量您的 plugin 所做的變更並在 CI 上進行把關
• 建立和分發市場：打包和共享您的 plugins
• Plugins 參考：完整的技術規格
• 深入探討特定的 plugin 元件：
  • Skills：skill 開發詳情
  • Subagents：agent 配置和功能
  • Hooks：事件處理和自動化
  • MCP：外部工具整合