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