本參考提供 Claude Code 外掛程式系統的完整技術規格，包括元件架構、CLI 命令和開發工具。
外掛程式元件參考
本節記錄外掛程式可提供的五種元件類型。
外掛程式新增自訂斜線命令，與 Claude Code 的命令系統無縫整合。
位置：外掛程式根目錄中的 commands/ 目錄
檔案格式：包含前置資料的 Markdown 檔案
如需外掛程式命令結構、呼叫模式和功能的完整詳細資訊，請參閱外掛程式命令。
外掛程式可提供專門的子代理，用於特定任務，Claude 可在適當時自動呼叫。
位置：外掛程式根目錄中的 agents/ 目錄
檔案格式：描述代理功能的 Markdown 檔案
代理結構：
---
description: 此代理的專長
capabilities: ["task1", "task2", "task3"]
---
# 代理名稱
詳細說明代理的角色、專業知識以及 Claude 應何時呼叫它。
## 功能
- 代理擅長的特定任務
- 另一項專門功能
- 何時使用此代理與其他代理
## 背景和範例
提供此代理應何時使用的範例以及它解決的問題類型。
- 代理出現在
/agents 介面中
- Claude 可根據任務背景自動呼叫代理
- 使用者可手動呼叫代理
- 外掛程式代理與內建 Claude 代理並行運作
外掛程式可提供代理技能來擴展 Claude 的功能。技能由模型呼叫 — Claude 根據任務背景自主決定何時使用它們。
位置：外掛程式根目錄中的 skills/ 目錄
檔案格式：包含具有前置資料的 SKILL.md 檔案的目錄
技能結構：
skills/
├── pdf-processor/
│ ├── SKILL.md
│ ├── reference.md (選用)
│ └── scripts/ (選用)
└── code-reviewer/
└── SKILL.md
- 安裝外掛程式時會自動發現外掛程式技能
- Claude 根據匹配的任務背景自主呼叫技能
- 技能可在 SKILL.md 旁邊包含支援檔案
如需 SKILL.md 格式和完整的技能編寫指南，請參閱：
外掛程式可提供事件處理程式，自動回應 Claude Code 事件。
位置：外掛程式根目錄中的 hooks/hooks.json，或內嵌在 plugin.json 中
格式：具有事件匹配器和動作的 JSON 設定
鉤子設定：
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
}
]
}
]
}
}
PreToolUse：Claude 使用任何工具之前PostToolUse：Claude 使用任何工具之後UserPromptSubmit：使用者提交提示時Notification：Claude Code 傳送通知時Stop：Claude 嘗試停止時SubagentStop：子代理嘗試停止時SessionStart：在工作階段開始時SessionEnd：在工作階段結束時PreCompact：在對話歷史記錄壓縮之前
鉤子類型：
command：執行 shell 命令或指令碼validation：驗證檔案內容或專案狀態notification：傳送警示或狀態更新
MCP 伺服器
外掛程式可捆綁模型背景協議 (MCP) 伺服器，以將 Claude Code 與外部工具和服務連接。
位置：外掛程式根目錄中的 .mcp.json，或內嵌在 plugin.json 中
格式：標準 MCP 伺服器設定
MCP 伺服器設定：
{
"mcpServers": {
"plugin-database": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
"env": {
"DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
}
},
"plugin-api-client": {
"command": "npx",
"args": ["@company/mcp-server", "--plugin-mode"],
"cwd": "${CLAUDE_PLUGIN_ROOT}"
}
}
}
- 啟用外掛程式時，外掛程式 MCP 伺服器會自動啟動
- 伺服器在 Claude 的工具組中顯示為標準 MCP 工具
- 伺服器功能與 Claude 的現有工具無縫整合
- 外掛程式伺服器可獨立於使用者 MCP 伺服器進行設定
外掛程式資訊清單架構
plugin.json 檔案定義外掛程式的中繼資料和設定。本節記錄所有支援的欄位和選項。
完整架構
{
"name": "plugin-name",
"version": "1.2.0",
"description": "Brief plugin description",
"author": {
"name": "Author Name",
"email": "[email protected]",
"url": "https://github.com/author"
},
"homepage": "https://docs.example.com/plugin",
"repository": "https://github.com/author/plugin",
"license": "MIT",
"keywords": ["keyword1", "keyword2"],
"commands": ["./custom/commands/special.md"],
"agents": "./custom/agents/",
"hooks": "./config/hooks.json",
"mcpServers": "./mcp-config.json"
}
必需欄位
| 欄位 | 類型 | 說明 | 範例 |
|---|
name | string | 唯一識別碼 (kebab-case，無空格) | "deployment-tools" |
中繼資料欄位
| 欄位 | 類型 | 說明 | 範例 |
|---|
version | string | 語義版本 | "2.1.0" |
description | string | 外掛程式用途的簡要說明 | "Deployment automation tools" |
author | object | 作者資訊 | {"name": "Dev Team", "email": "[email protected]"} |
homepage | string | 文件 URL | "https://docs.example.com" |
repository | string | 原始程式碼 URL | "https://github.com/user/plugin" |
license | string | 授權識別碼 | "MIT"、"Apache-2.0" |
keywords | array | 探索標籤 | ["deployment", "ci-cd"] |
元件路徑欄位
| 欄位 | 類型 | 說明 | 範例 |
|---|
commands | string|array | 其他命令檔案/目錄 | "./custom/cmd.md" 或 ["./cmd1.md"] |
agents | string|array | 其他代理檔案 | "./custom/agents/" |
hooks | string|object | 鉤子設定路徑或內嵌設定 | "./hooks.json" |
mcpServers | string|object | MCP 設定路徑或內嵌設定 | "./mcp.json" |
路徑行為規則
重要：自訂路徑補充預設目錄 - 它們不會取代預設目錄。
- 如果
commands/ 存在，除了自訂命令路徑外，還會載入它
- 所有路徑必須相對於外掛程式根目錄，並以
./ 開頭
- 來自自訂路徑的命令使用相同的命名和命名空間規則
- 可以將多個路徑指定為陣列以提高靈活性
路徑範例：
{
"commands": [
"./specialized/deploy.md",
"./utilities/batch-process.md"
],
"agents": [
"./custom-agents/reviewer.md",
"./custom-agents/tester.md"
]
}
環境變數
${CLAUDE_PLUGIN_ROOT}：包含外掛程式目錄的絕對路徑。在鉤子、MCP 伺服器和指令碼中使用此變數，以確保無論安裝位置如何都能使用正確的路徑。
{
"hooks": {
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
}
]
}
]
}
}
外掛程式目錄結構
標準外掛程式配置
完整的外掛程式遵循此結構：
enterprise-plugin/
├── .claude-plugin/ # 中繼資料目錄
│ └── plugin.json # 必需：外掛程式資訊清單
├── commands/ # 預設命令位置
│ ├── status.md
│ └── logs.md
├── agents/ # 預設代理位置
│ ├── security-reviewer.md
│ ├── performance-tester.md
│ └── compliance-checker.md
├── skills/ # 代理技能
│ ├── code-reviewer/
│ │ └── SKILL.md
│ └── pdf-processor/
│ ├── SKILL.md
│ └── scripts/
├── hooks/ # 鉤子設定
│ ├── hooks.json # 主要鉤子設定
│ └── security-hooks.json # 其他鉤子
├── .mcp.json # MCP 伺服器定義
├── scripts/ # 鉤子和公用程式指令碼
│ ├── security-scan.sh
│ ├── format-code.py
│ └── deploy.js
├── LICENSE # 授權檔案
└── CHANGELOG.md # 版本歷史記錄
.claude-plugin/ 目錄包含 plugin.json 檔案。所有其他目錄 (commands/、agents/、skills/、hooks/) 必須位於外掛程式根目錄，而不是在 .claude-plugin/ 內。
檔案位置參考
| 元件 | 預設位置 | 用途 |
|---|
| 資訊清單 | .claude-plugin/plugin.json | 必需的中繼資料檔案 |
| 命令 | commands/ | 斜線命令 Markdown 檔案 |
| 代理 | agents/ | 子代理 Markdown 檔案 |
| 技能 | skills/ | 具有 SKILL.md 檔案的代理技能 |
| 鉤子 | hooks/hooks.json | 鉤子設定 |
| MCP 伺服器 | .mcp.json | MCP 伺服器定義 |
偵錯和開發工具
偵錯命令
使用 claude --debug 查看外掛程式載入詳細資訊：
這會顯示：
- 正在載入哪些外掛程式
- 外掛程式資訊清單中的任何錯誤
- 命令、代理和鉤子註冊
- MCP 伺服器初始化
常見問題
| 問題 | 原因 | 解決方案 |
|---|
| 外掛程式未載入 | 無效的 plugin.json | 驗證 JSON 語法 |
| 命令未出現 | 目錄結構錯誤 | 確保 commands/ 在根目錄，而不是在 .claude-plugin/ 中 |
| 鉤子未觸發 | 指令碼不可執行 | 執行 chmod +x script.sh |
| MCP 伺服器失敗 | 缺少 ${CLAUDE_PLUGIN_ROOT} | 對所有外掛程式路徑使用變數 |
| 路徑錯誤 | 使用絕對路徑 | 所有路徑必須相對且以 ./ 開頭 |
發佈和版本控制參考
版本管理
遵循外掛程式發行的語義版本控制：
## 另請參閱
- [外掛程式](/zh-TW/plugins) - 教學和實際使用
- [外掛程式市場](/zh-TW/plugin-marketplaces) - 建立和管理市場
- [斜線命令](/zh-TW/slash-commands) - 命令開發詳細資訊
- [子代理](/zh-TW/sub-agents) - 代理設定和功能
- [代理技能](/zh-TW/skills) - 擴展 Claude 的功能
- [鉤子](/zh-TW/hooks) - 事件處理和自動化
- [MCP](/zh-TW/mcp) - 外部工具整合
- [設定](/zh-TW/settings) - 外掛程式的設定選項
