> ## Documentation Index
> Fetch the complete documentation index at: https://felimet-hub.jmcores.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 04-7 Plugin 的正確使用：超越 Quick Start 的 know-how

> 多數人照 Quick Start 裝完 plugin 就以為結束了，卻說不清楚它裝了什麼、提供了哪些能力、怎麼完整配置。本單元講 plugin 目錄結構、裝後盤點 SOP、進階配置、版本管理，以及拿起 plugin 之前的安全評估 SOP。

export const LearnerPrimer = ({items = [], lang = "zh"}) => {
  const t = lang === "en" ? {
    title: "Before this unit, be honest with yourself",
    sub: "If you can't answer these, that gap is exactly what this unit closes."
  } : {
    title: "讀這個單元前，先誠實面對",
    sub: "這幾題答不出來，正是這個單元要替你補的洞。"
  };
  const css = `
  .lp-root{--lp-bg:#FAF7F1;--lp-surface:rgba(191,117,81,0.05);--lp-border:rgba(0,0,0,0.09);--lp-edge:rgba(191,117,81,0.42);--lp-text:#2b2722;--lp-dim:#6f6a62;--lp-accent:#bf7551;border:1px solid var(--lp-border);border-left:3px solid var(--lp-edge);border-radius:13px;background:var(--lp-bg);color:var(--lp-text);overflow:hidden;margin:1.25rem 0;}
  .dark .lp-root{--lp-bg:#1b1a18;--lp-surface:rgba(207,138,104,0.07);--lp-border:rgba(255,255,255,0.08);--lp-edge:rgba(207,138,104,0.5);--lp-text:#e7e3da;--lp-dim:#a8a299;--lp-accent:#cf8a68;}
  .lp-head{display:flex;align-items:center;gap:9px;padding:13px 18px 11px;border-bottom:1px solid var(--lp-border);background:var(--lp-surface);}
  .lp-ic{color:var(--lp-accent);flex-shrink:0;}
  .lp-htx{display:flex;flex-direction:column;gap:1px;min-width:0;}
  .lp-title{font-size:14px;font-weight:650;line-height:1.3;letter-spacing:.01em;}
  .lp-sub{font-size:12px;color:var(--lp-dim);line-height:1.4;}
  .lp-list{list-style:none;margin:0;padding:10px 18px 14px;display:flex;flex-direction:column;gap:0;}
  .lp-item{display:flex;align-items:baseline;gap:11px;padding:7px 0;font-size:14px;line-height:1.6;border-top:1px solid var(--lp-border);}
  .lp-item:first-child{border-top:none;}
  .lp-mark{flex-shrink:0;color:var(--lp-accent);font-size:13px;font-weight:700;line-height:1.55;font-variant-numeric:tabular-nums;opacity:.85;}
  .lp-q{flex:1 1 0;min-width:0;color:var(--lp-text);}
  @media (max-width:620px){.lp-head{padding:12px 14px 10px;}.lp-list{padding:8px 14px 12px;}}
  `;
  return <div className="lp-root">
      <style>{css}</style>
      <div className="lp-head">
        <svg className="lp-ic" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><circle cx="12" cy="12" r="10" /><circle cx="12" cy="12" r="6" /><circle cx="12" cy="12" r="2" /></svg>
        <span className="lp-htx">
          <span className="lp-title">{t.title}</span>
          <span className="lp-sub">{t.sub}</span>
        </span>
      </div>
      <ul className="lp-list">
        {items.map((q, i) => <li className="lp-item" key={i}>
            <span className="lp-mark">{String(i + 1).padStart(2, "0")}</span>
            <span className="lp-q">{q}</span>
          </li>)}
      </ul>
    </div>;
};

<LearnerPrimer
  lang="zh"
  items={[
"裝完一個 plugin 不等於會用。",
"沒盤點 hook 就啟用，陌生程式碼在常態跑。",
"你裝 plugin 是 Quick Start 看起來酷，還是真痛點？",
"同名 skill 衝突時，你怪模型行為異常是錯怪。",
"省略 version 給生產用，main 一壞你就跟著壞。",
"改 plugin 內 Subagent frontmatter，下次更新被覆蓋。",
"多 plugin 各自管同類 lint hook，疊加執行浪費資源。",
]}
/>

<Info>
  **這個單元解決什麼問題**

  多數人照 Quick Start 裝完 plugin 就以為結束了，卻說不清楚它裝了什麼、提供了哪些能力、怎麼完整配置；這是知其然不知其所以然的典型。Claude Code v2.1 起 plugin 是「打包發布 skills、agents、hooks、MCP / LSP 設定、背景監控的單元」，透過兩個公開市集（`claude-plugins-official` 與 `claude-community`）分發。本單元講 plugin 目錄結構、裝後盤點 SOP、超越 Quick Start 的進階配置、版本管理，以及拿起 plugin 之前的安全評估 SOP。
</Info>

## 學習目標

* [ ] 說出一個 plugin 打包了哪些元件（skills、agents、commands、hooks、`.mcp.json`、`.lsp.json`、monitors、`bin/`、`settings.json`），以及各自在系統裡扮演的角色。
* [ ] 裝完一個 plugin 後，主動盤點它實際提供了哪些 skill / agent / command / hook / MCP server，而非依賴 Quick Start 的片面說明。
* [ ] 做超越 Quick Start 的完整配置：環境變數、與既有設定的衝突排解、模型選擇、預載 skills。
* [ ] 區分 `claude --plugin-dir`（本機開發）、`--plugin-url`（CI artifact）、`/plugin install`（市集）三條安裝路徑的使用時機。
* [ ] 套 03-1 評估框架與 03-3 安全原則，決定一個 plugin 該不該裝、要不要保留、要不要限縮其 hook 或 MCP 權限。

***

## 1. Plugin 是什麼：打包成一包的能力集合

Plugin 是一個**目錄**，內含 manifest 與一組元件：skills、agents、commands、hooks、MCP server 設定、LSP server 設定、背景監控、可執行檔。它把「單一專案用 `.claude/` 散裝設定」升級成**可分發、可版本化、跨專案共用**的單元（截至 2026-06 依官方 plugins 章節 \[1]）。

安裝一個 plugin 實際在做的事：

* 把元件目錄與檔案註冊到 Claude Code 的載入清單。
* 透過 `plugin.json` 的 `name` 為所有 Skill / Command 加 namespace 前綴（`/plugin-name:skill-name`）。
* 啟用內含的 MCP server 與 LSP server 設定。
* 套用 `settings.json` 的預設值（限 `agent` 與 `subagentStatusLine` 兩個 key）\[1]。

<Tip>
  **為什麼會需要 plugin 而不是只在 `.claude/` 寫**

  跨專案共用：同一份 API 慣例、code review agent、post-tool formatter 在多個 repo 都用得上，總不能每個 repo 重寫。版本化：plugin 有 `version` 欄位，可設 pinned 鎖版本，避免「自動追蹤 main 結果今天更新壞了」的情境。分發：透過市集讓團隊成員或社群一鍵安裝，不必手動 clone + 設定路徑。Namespace 隔離：plugin skill 一律 namespaced（`/plugin-name:hello`），不同 plugin 同名 skill 不會互相覆蓋。
</Tip>

## 2. Plugin 與獨立 `.claude/` 配置的差別

Claude Code 支援兩種方式加自訂 skills、agents、hooks（\[1]）：

| 面向        | 獨立配置（`.claude/`）  | Plugin                                    |
| --------- | ----------------- | ----------------------------------------- |
| Skill 命名  | `/hello`（短、無前綴）   | `/my-plugin:hello`（namespaced）            |
| 適合        | 個人工作流、單一專案客製、快速實驗 | 跨專案共用、團隊分發、社群市集、版本化                       |
| 分發方式      | 透過版控（隨 repo 走）    | 透過市集或 git URL                             |
| 版本管理      | 隨 repo 走          | 顯式 `version` 欄位或 git commit SHA           |
| Hook 設定位置 | `settings.json` 內 | `hooks/hooks.json`（與設定分離）                 |
| 安裝指令      | 編輯檔案              | `/plugin install` 或 `claude --plugin-dir` |

<Tip>
  **起手策略**

  先在 `.claude/` 獨立配置快速迭代、驗證流程值得封裝，**再**轉成 plugin 分發（\[1]）。這個順序避免「花三小時打包一個用不到的功能」。
</Tip>

## 3. 目錄結構

完整的 plugin 目錄結構（截至 2026-06）\[1]：

<Tree>
  <Tree.Folder name="my-plugin/" defaultOpen>
    <Tree.Folder name=".claude-plugin/" defaultOpen>
      <Tree.File name="plugin.json · 必要：manifest" />
    </Tree.Folder>

    <Tree.Folder name="skills/ · 選填：Agent Skills">
      <Tree.Folder name="code-review/">
        <Tree.File name="SKILL.md" />

        <Tree.Folder name="references/" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="commands/ · 選填：使用者主動觸發的 command">
      <Tree.File name="deploy.md" />
    </Tree.Folder>

    <Tree.Folder name="agents/ · 選填：自訂 Subagent">
      <Tree.File name="security-reviewer.md" />
    </Tree.Folder>

    <Tree.Folder name="hooks/ · 選填：事件 handler">
      <Tree.File name="hooks.json" />
    </Tree.Folder>

    <Tree.File name=".mcp.json · 選填：MCP server 設定" />

    <Tree.File name=".lsp.json · 選填：LSP server 設定" />

    <Tree.Folder name="monitors/ · 選填：背景監控">
      <Tree.File name="monitors.json" />
    </Tree.Folder>

    <Tree.Folder name="bin/ · 選填：plugin 啟用時加入 PATH 的可執行檔" />

    <Tree.File name="settings.json · 選填：plugin 啟用時套用的預設值" />

    <Tree.File name="README.md · 建議：人類可讀的說明" />
  </Tree.Folder>
</Tree>

<Warning>
  **不要把 `commands/`、`agents/`、`skills/`、`hooks/` 放進 `.claude-plugin/` 內**

  官方反覆強調這條（\[1]）：**只有 `plugin.json` 該在 `.claude-plugin/` 內**。所有其他目錄必須在 plugin 根目錄層。這是常見錯誤，會讓 plugin 載入時找不到元件。
</Warning>

## 4. Manifest：`.claude-plugin/plugin.json`

最小 manifest \[1]：

```json theme={null}
{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
```

| 欄位            | 用途                                                                            |
| ------------- | ----------------------------------------------------------------------------- |
| `name`        | 唯一識別，同時是 skill namespace 前綴。`/my-first-plugin:hello` 的 `my-first-plugin` 就是這值 |
| `description` | 在 plugin manager 顯示，供使用者判斷這個 plugin 的用途                                       |
| `version`     | 選填。**若設了，使用者只在版本變動時收到更新**。若省略，git 分發時以 commit SHA 為版本，每次 commit 算新版本 \[1]     |
| `author`      | 選填，作者資訊（name、email）                                                           |
| `homepage`    | 選填，plugin 首頁                                                                  |
| `repository`  | 選填，源碼 repo                                                                    |
| `license`     | 選填，授權條款                                                                       |

完整 schema 見官方 plugins reference \[2]。

## 5. 各元件怎麼放

### 5.1 Skills

Skills 用**目錄**形式放 `skills/<name>/SKILL.md`，與獨立配置同（\[1]，並見 [04-4 Skill](/code-agent/customization/skills)）：

<Tree>
  <Tree.Folder name="my-plugin/" defaultOpen>
    <Tree.Folder name="skills/" defaultOpen>
      <Tree.Folder name="code-review/" defaultOpen>
        <Tree.File name="SKILL.md" />

        <Tree.Folder name="references/">
          <Tree.File name="style-guide.md" />
        </Tree.Folder>
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Tree>

每個 SKILL.md 用 YAML frontmatter 與 `description`：

```yaml theme={null}
---
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
```

裝好 plugin 後跑 `/reload-plugins` 才會載入。完整 Skill 撰寫規範見 [04-4 Skill](/code-agent/customization/skills)。

### 5.2 Commands

Commands 放 `commands/<name>.md` 單檔（\[1]，並見 [04-3 Command](/code-agent/customization/commands)）：

<Tree>
  <Tree.Folder name="my-plugin/" defaultOpen>
    <Tree.Folder name="commands/" defaultOpen>
      <Tree.File name="deploy.md" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

<Note>
  **`commands/` 對 plugin 是 legacy 形式**

  官方在 v2.1 文件中明示「Use `skills/` for new plugins」（\[1]）。新 plugin 應把命令式邏輯放 `skills/<name>/SKILL.md` 內，享有目錄式結構、`references/`、`scripts/` 與 progressive disclosure。
</Note>

### 5.3 Agents

Subagent 放 `agents/<name>.md`，frontmatter 與獨立配置同（見 [04-5 Subagent](/code-agent/customization/subagents)）。**Plugin Subagent 有三個限制**（\[1]）：`hooks`、`mcpServers`、`permissionMode` 三個 frontmatter 欄位被忽略。

<Warning>
  **Plugin Subagent 的限制**

  安全考量，Plugin Subagent 不支援 `hooks`、`mcpServers`、`permissionMode` 欄位 \[1]。需要這三個時把 agent 檔複製到 `.claude/agents/` 或 `~/.claude/agents/`。另一條路是在 `settings.json` 的 `permissions.allow` 加規則，但該規則適用整個 session，無法只限 plugin agent。
</Warning>

### 5.4 Hooks

Hook 設定放 `hooks/hooks.json`，**與 `settings.json` 的 `hooks` 區塊同樣格式**（\[1]）：

```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }
        ]
      }
    ]
  }
}
```

Hook command 透過 stdin 收到 hook 輸入 JSON；用 `jq` 解出欄位（範例見 [04-6 Hooks](/code-agent/customization/hooks)）。

### 5.5 MCP servers

`.mcp.json` 與獨立配置同 schema（\[1]）：

```json theme={null}
{
  "github": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```

Plugin 啟用時，這些 MCP server 自動連線到主 session。

### 5.6 LSP servers

LSP（Language Server Protocol）server 給 Claude 即時程式碼智慧（\[1]）。`.lsp.json` 範例：

```json theme={null}
{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
```

<Tip>
  **優先用官方市集的預建 LSP**

  對 TypeScript、Python、Rust 等主流語言，**直接從 `claude-plugins-official` 市集安裝預建的 LSP plugin**。只有需要官方沒覆蓋的語言才自建 LSP plugin \[1]。
</Tip>

### 5.7 Monitors

Monitors 讓 plugin 在背景 watch log、檔案、外部狀態，事件發生時通知 Claude（\[1]）。`monitors/monitors.json`：

```json theme={null}
[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]
```

`command` 的每一行 stdout 視為一個 notification 傳給 Claude。完整 schema 含 `when` 觸發與變數替換，見 \[2]。

### 5.8 bin/

`bin/` 內的可執行檔在 plugin 啟用時加入 `Bash` tool 的 `PATH` \[1]。**謹慎放**：每個可執行檔都是你 shell 上隨時可叫用的指令，可能被任何 hook 或 agent 觸發。

### 5.9 預設 settings

Plugin 根目錄的 `settings.json` 啟用時套用預設值。**目前只支援兩個 key**（\[1]）：`agent` 與 `subagentStatusLine`。

```json theme={null}
{
  "agent": "security-reviewer"
}
```

這會把 plugin 的 `agents/security-reviewer.md` 設為主 session 的 agent。未知的 key 會被靜默忽略。

## 6. 安裝：四條路徑

依使用場景選對應的安裝方式：

| 路徑              | 指令                                                      | 用途                                                  |
| --------------- | ------------------------------------------------------- | --------------------------------------------------- |
| 本機開發            | `claude --plugin-dir ./my-plugin`                       | 開發、測試、debug                                         |
| ZIP 本機          | `claude --plugin-dir ./my-plugin.zip`                   | 同上但用打包好的版本（v2.1.128+）\[1]                           |
| URL CI artifact | `claude --plugin-url https://example.com/my-plugin.zip` | CI 產出的 plugin 載入測試                                  |
| 市集              | `/plugin install <name>`                                | 從 `claude-plugins-official` 或 `claude-community` 安裝 |

### 6.1 本機開發模式

`--plugin-dir` 直接載入指定目錄，不需安裝步驟（\[1]）：

```bash theme={null}
claude --plugin-dir ./my-plugin
```

多個 plugin 同時載入（重複 flag）：

```bash theme={null}
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
```

開發中改完 plugin，跑 `/reload-plugins` 重載，不用重啟。

### 6.2 從市集安裝

市集是用 `/plugin` 命令管理。安裝流程（\[1]）：

```
/plugin                                  # 開啟 plugin manager
# 在市集頁面選擇 plugin，按指示安裝
```

或用指令式：

```
/plugin install <plugin-name>            # 從已加入的市集安裝
/plugin marketplace add anthropics/claude-plugins-community
```

### 6.3 兩個公開市集

Anthropic 維護兩個公開市集（\[1]）：

* **`claude-plugins-official`**：Anthropic 策展的精選 plugin。**每個 Claude Code 安裝自動可用**。
* **`claude-community`**：第三方提交、經 review 後上架的社群市集。使用者用 `/plugin marketplace add anthropics/claude-plugins-community` 加入，從 `@claude-community` 安裝。

<Note>
  **兩者差異**

  `claude-plugins-official` 策展方式由 Anthropic 全權決定，無申請流程；提交表單不會把 plugin 放進這裡。`claude-community` 透過審核 pipeline：跑 `claude plugin validate` 自動檢查 + 自動安全篩選，通過後 pin 在 `anthropics/claude-plugins-community` 倉庫的特定 commit SHA，CI 在你推新 commit 時自動 bump pin。catalog 每晚同步，所以通過到可安裝可能有 24 小時延遲。

  提交審核入口：claude.ai/settings/plugins/submit 或 platform.claude.com/plugins/submit。
</Note>

### 6.4 Private 市集（團隊內部分發）

團隊可在私有 repo 架市集，只讓組織成員存取。詳細機制見 \[2]。

## 7. 裝後盤點 SOP：別只看 Quick Start

<Note>
  **30 分鐘盤點流程**

  裝完 plugin 後，依下列步驟做盤點。**這是「裝完等於會用」與「裝完只啟動 20%」的差距所在。**
</Note>

<Steps>
  <Step title="讀 manifest">
    開 `~/.claude/plugins/<plugin-name>/.claude-plugin/plugin.json`，記下 `name`、`version`、`author`、`description`、`homepage`（若有）。
  </Step>

  <Step title="列出所有元件">
    ```bash theme={null}
    PLUGIN=~/.claude/plugins/<plugin-name>
    echo "=== skills ==="
    find "$PLUGIN/skills" -name "SKILL.md" 2>/dev/null
    echo "=== commands ==="
    ls "$PLUGIN/commands" 2>/dev/null
    echo "=== agents ==="
    ls "$PLUGIN/agents" 2>/dev/null
    echo "=== hooks ==="
    cat "$PLUGIN/hooks/hooks.json" 2>/dev/null
    echo "=== mcp servers ==="
    cat "$PLUGIN/.mcp.json" 2>/dev/null
    echo "=== lsp servers ==="
    cat "$PLUGIN/.lsp.json" 2>/dev/null
    echo "=== monitors ==="
    cat "$PLUGIN/monitors/monitors.json" 2>/dev/null
    echo "=== bin ==="
    ls "$PLUGIN/bin" 2>/dev/null
    echo "=== settings ==="
    cat "$PLUGIN/settings.json" 2>/dev/null
    ```
  </Step>

  <Step title="在 Claude Code 內確認">
    跑 `/help`，看 plugin 的 skill / command 列表（會帶 namespace 前綴）。跑 `/agents`，看 plugin 的 agent 是否有出現在 Library。在對話中問 Claude：「列出當前 session 啟用的 plugin 與其提供的 skill / MCP server」。
  </Step>

  <Step title="逐一讀 SKILL.md / agent.md / hooks.json">
    **不要跳過**。每個檔 30 秒掃過，知道它做什麼、什麼時候觸發、是否需要 arg、是否動態注入 shell 指令。對 hooks.json 每個 `command` 跑本單節後段的供應鏈掃描（`rg` 搜尋可疑字串）。
  </Step>

  <Step title="記下設定覆寫點">
    plugin 的 `settings.json` 寫了什麼（目前只 `agent` 與 `subagentStatusLine`）。plugin 的 MCP server 啟動時需要哪些環境變數（看 `.mcp.json` 的 `env` 欄位）。你自己的 `settings.json` 有沒有同名的設定會被 plugin 覆寫（plugin 內 settings.json 優先序規則見 \[2]）。
  </Step>
</Steps>

這個盤點 SOP 暴露的常見盲點：裝完一個「看起來會做 code review」的 plugin，盤點後才發現它還內含一個 `lint-on-save` hook 在 `PostToolUse: Write|Edit` 觸發，Quick Start 沒提。

## 8. 完整配置：超越 Quick Start

Quick Start 通常只示範 1-2 個 happy path。進階設定常藏在細節裡。

### 8.1 環境變數與 secrets

Plugin 的 `.mcp.json` 與 `monitors/monitors.json` 常引用環境變數（`${GITHUB_TOKEN}` 等）。Quick Start 設最少必要項，你需要：

* 確認本機或 CI 環境有那些變數。
* 透過環境變數管理工具（1Password CLI、`.env` 與 direnv、雲端 secret manager）注入，**不要 hardcode 在 plugin 設定檔**；plugin 進版控。

### 8.2 同名 skill / command 衝突

Plugin 的 skill 一定 namespaced（`/plugin-name:hello`），但**獨立配置（`.claude/commands/`）的同名 command 仍可能與 plugin 的 `commands/<name>.md` 衝突**。優先序規則（截至 2026-06，詳細見 \[2]）：

* 獨立配置優先（先載入、優先匹配）。
* Plugin command 後載入。
* 同名時獨立配置勝出。

但若獨立配置被移除，plugin command 才生效。**盤點時主動檢查這層**：你的 `.claude/commands/deploy.md` 與某 plugin 的 `commands/deploy.md` 同名嗎？

### 8.3 Hook 執行順序

多個 hook 對同一事件觸發時，**執行順序依設定位置**（\[1]）：`settings.json` 的 hook 優先，再來是 plugin 的 `hooks/hooks.json`。若多個 plugin 都有同 matcher 的 PostToolUse，全部依序跑。**沒有去抖或優先序手動設定**，若你的格式化 hook 與某 plugin 的格式化 hook 對同一檔重複處理，需要手動整合。

### 8.4 MCP server port 衝突

若兩個 plugin 都要在同一 port 起 server，後啟動的會 fail。檢查 plugin 的 `.mcp.json`：

* `command` 是 `node` / `python` / `npx` 啟動，port 通常由 server 動態選，較少衝突。
* 若硬編 port（如 `localhost:8080`），手動改到不同 port。

### 8.5 模型選擇

部分 plugin 的 Subagent 預設繼承主對話模型。對重複性高的 worker（code formatter、test runner），把 frontmatter `model: haiku` 改掉能省下大量成本（見 [04-5 Subagent](/code-agent/customization/subagents)）。

<Warning>
  **Plugin Subagent 改 frontmatter 是「分叉」**

  你改了 plugin 內的 Subagent frontmatter，**下次該 plugin 更新時你的改動會被覆蓋**。長期做法：把整個 plugin fork 維護、或用獨立 Subagent 取代那個功能。
</Warning>

### 8.6 用 `claude plugin init` 起步

`claude plugin init my-tool` scaffold 一個 plugin 骨架到 `~/.claude/skills/my-tool/`，含 `.claude-plugin/plugin.json` manifest 與 starter `SKILL.md`。下次 session 自動以 `my-tool@skills-dir` 載入，不需 marketplace 步驟（\[1]）。

## 9. 版本管理

Plugin 兩種版本模式（\[1]）：

| 模式           | 觸發                     | 行為                 |
| ------------ | ---------------------- | ------------------ |
| 顯式 `version` | 該欄位變動                  | 使用者只在新版本收到更新       |
| 隱式（git SHA）  | 省略 `version` 且走 git 分發 | **每次 commit 算新版本** |

<Warning>
  **省略 `version` 的代價**

  對開發者方便，但你裝的 plugin 會「每次 commit 自動更新」。一次 breaking commit 進 main 就破壞你工作流。**生產環境用顯式 `version` 鎖版**。開發階段可省略。
</Warning>

更新策略：

* **Production 鎖版**：固定 `version` 欄位，僅在 review PR 後 bump。
* **Dev 追蹤**：省略 `version`、用 `claude --plugin-dir` 連到本地目錄。
* **團隊內部分發**：透過私有市集 + git tag，CI bump 版本。

## 10. 從獨立配置遷移到 plugin

若你已經有 `.claude/commands/`、`agents/`、`skills/`，可遷移成 plugin（\[1]）：

```bash theme={null}
# 1. 建 plugin 結構
mkdir -p my-plugin/.claude-plugin
echo '{"name": "my-plugin", "description": "...", "version": "1.0.0"}' \
  > my-plugin/.claude-plugin/plugin.json

# 2. 複製元件
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

# 3. 遷移 hooks
mkdir my-plugin/hooks
# 從 .claude/settings.json 抄 hooks 區塊到 my-plugin/hooks/hooks.json
#（格式相同）

# 4. 測試
claude --plugin-dir ./my-plugin

# 5. 驗證每個元件：跑 skills、檢查 agents 出現、驗證 hooks 觸發
```

<Tip>
  **遷移後清掉原檔**

  遷移完成、plugin 載入正常後，把原 `.claude/` 內的對應檔刪除，避免重複載入 \[1]。
</Tip>

## 11. 安全與評估

Plugin = 你不完全控制的程式碼進入工作環境。風險面：

### 11.1 供應鏈評估

| 維度    | 評估點                                                                      |
| ----- | ------------------------------------------------------------------------ |
| 維護者   | 是誰？單人還是組織？社群評價？過去 commit 活躍度？                                            |
| 更新頻率  | 上次 commit 是何時？若 plugin 一年沒更新，套用前先測試                                      |
| 來源    | 從 `claude-plugins-official`、經審核的 `claude-community`、還是私人 git URL？信任程度差很多 |
| 程式碼審查 | 讀過 manifest 與每個 SKILL.md / hooks.json / .mcp.json 嗎？                     |
| 已知漏洞  | Snyk ToxicSkills（2026-02）研究指出公開 skill 中 36% 含 prompt injection           |

### 11.2 引入前掃描

照 [04-6 Hooks](/code-agent/customization/hooks) 的 SOP 對 `hooks/hooks.json` 與每個 SKILL.md 跑：

```bash theme={null}
PLUGIN=~/.claude/plugins/<plugin-name>

# 1. 可疑外連
rg -n 'curl|wget|nc|ssh|ANTHROPIC_BASE_URL|enableAllProjectMcpServers' "$PLUGIN/"

# 2. 隱藏 Unicode
rg -nP '[\x{200B}-\x{200D}\x{202A}-\x{202E}]' "$PLUGIN/"

# 3. HTML 註解、script tag、base64
rg -n '<!--|<script|data:text/html|base64,' "$PLUGIN/"

# 4. 可疑權限或外連（重複確認）
rg -n 'curl|wget|nc|scp|ssh|enableAllProjectMcpServers|ANTHROPIC_BASE_URL' "$PLUGIN/"
```

任何 hit 都要人工 review 上下文再決定裝不裝。

### 11.3 限縮 plugin 權限

裝完後若不放心它的 hook 或 MCP 權限：

* **停用全部 hooks**：`settings.json` 設 `"disableAllHooks": true`（plugin 內 hook 也一起停；managed 級 hook 不受影響）\[1]。
* **deny 特定 MCP server**：在 `settings.json` 的 `permissions.deny` 設。
* **fork plugin**：把整個 plugin 複製到本地、移除你擔心的部分、改 `name` 為 `<name>-local`，用 `claude --plugin-dir` 載入。

### 11.4 與 03-1 評估框架連動

引入 plugin 前跑 [03-1 評估框架](/code-agent/judgment/fit-evaluation)：

* 這個 plugin 解決的問題，是我工作流裡真實的高頻痛點嗎？還是 Quick Start 看起來酷？
* 試用一個禮拜：實際上每天叫用幾次？省下的時間是否值得引入的供應鏈風險？
* 有沒有更小、更可信的替代方案（例如只裝 plugin 的一個 skill，獨立配置）？

不要照 Quick Start 評估，那只是「最短路徑示範」，不是「值得裝的理由」。

## 12. 工具對照

各家「plugin / 擴充包」機制在名稱與架構上差異顯著（截至 2026-06）：

| 概念     | Anthropic Claude（主範本）                                                     | OpenAI Codex                                          | Google Antigravity                                         | GitHub Copilot CLI                               | Cursor（短提）                               |
| ------ | ------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------- |
| 擴充包單位  | Plugin（manifest + skills/agents/hooks/mcp/lsp/monitors/bin/settings）      | Codex extension（`config.toml` + `extensions/<name>/`） | Antigravity extension（`~/.gemini/antigravity/extensions/`） | Copilot Extensions（GitHub Marketplace 上的第三方 app） | Cursor extensions（`.cursor/extensions/`） |
| 命名空間   | 必加 namespace（`/plugin-name:hello`）                                        | 設定式                                                   | 設定式                                                        | 無 namespace                                      | 設定式                                      |
| 安裝方式   | `claude --plugin-dir`、`/plugin install`、市集                                | `codex extension install`                             | 設定式                                                        | Marketplace UI                                   | 設定式                                      |
| 列出已安裝  | `/plugin` 指令、檔案系統掃描                                                       | `codex extension list`                                | 設定式                                                        | 設定式                                              | 設定式                                      |
| 設定覆蓋點  | `settings.json`（plugin 啟用時套用）、`hooks/hooks.json`、`monitors/monitors.json` | 設定式                                                   | 設定式                                                        | 設定式                                              | 設定式                                      |
| 安全掃描機制 | 無內建；手動 `rg` 掃                                                             | 設定式                                                   | 設定式                                                        | 設定式                                              | 設定式                                      |
| 公開市集   | `claude-plugins-official`（預設啟用）+ `claude-community`（使用者加入）                | 無統一公開市集                                               | 設定式                                                        | GitHub Marketplace                               | 設定式                                      |
| 版本管理   | 顯式 `version` 或 git commit SHA                                             | 設定式                                                   | 設定式                                                        | 設定式                                              | 設定式                                      |

<Note>
  **命名澄清**

  Claude Code plugin 與「Copilot Extensions」是不同東西：前者是本機 CLI 的目錄式擴充；後者是 GitHub Marketplace 上的第三方 app，通常整合雲端服務（issue tracker、CI 平台、雲端 provider）。本表只比較同類機制。OpenAI Codex、Antigravity、Cursor 的 plugin / extension 機制在命名與架構上各異，細節以各家當前官方文件為準。Cursor 為第三方 IDE（Anysphere），本 Playbook 僅短提一欄。
</Note>

## 13. 自我檢核動手做

<Note>
  **30 分鐘練習**

  1. **盤點現有 plugin**：用本單節的 `find` / `cat` SOP 對你最常用的 plugin 跑一次；列出它實際提供的 5 個元件（含 Quick Start 沒提的），以及每個元件觸發時機。
  2. **安全掃描**：對同一 plugin 跑 `rg` 掃描（4 條指令），把所有 hit 記下來並人工 review 上下文。
  3. **本機開發測試**：在 `~/playground/my-test-plugin/` 建一個空 plugin（`claude plugin init my-test-plugin`），加一個 SKILL 與一個 PostToolUse hook，用 `claude --plugin-dir` 載入測試，觀察 namespace 與 hook 觸發。
  4. **fork 一個現成 plugin**：把某個你裝的 plugin 從 `~/.claude/plugins/` 完整複製到本地目錄，移除 hook 區塊，改 `name` 為 `<原名>-no-hooks`，用 `claude --plugin-dir` 載入驗證 hooks 沒跑。
  5. **提交前驗證**：若你寫了 plugin 想要 submit 到 `claude-community`，先跑 `claude plugin validate` 跑過自動檢查。
</Note>

## 14. 常見誤區

<Warning>
  **反模式清單**

  * **把 Quick Start 當完整文件**：Quick Start 只是最短路徑示範，plugin 真正的能力集合通常大得多。不盤點就以為「裝完等於會用」。
  * **沒盤點 hook 就啟用 plugin**：hook 會在每次對應工具呼叫時自動執行，裝進未審查的 hook 等於讓陌生程式碼常態跑在你的工作環境。
  * **把 plugin 衝突歸咎於「模型行為異常」**：同名 skill 覆蓋、hook 執行序衝突等問題都是可排查的確定性問題，不是隨機性。
  * **省略 `version` 給生產環境用**：每次 commit 算新版本，main 分支上不小心壞了你就跟著壞。
  * **把 plugin 內 SKILL.md / agent.md 當成「進版控但不會動」**：plugin 更新時你的 `.claude/` 內 fork 版本會被覆蓋。要長期改須 fork 自己維護。
  * **裝多個 plugin 各自管同類 lint / format hook**：每次 Write / Edit 觸發多個 hook 疊加執行，浪費資源。整合到一個自製 plugin 或關掉多餘的。
  * **從私人 URL 裝 plugin 沒先讀原始碼**：`claude --plugin-url` 載入 CI artifact 是方便，但對私人 URL 一律先讀原始碼、跑 `rg` 掃描。
</Warning>

## 自我檢核

<Check>
  **通過本單元的標準**

  1. 你能說出 plugin 打包的 9 種元件嗎（skills、commands、agents、hooks、`.mcp.json`、`.lsp.json`、monitors、`bin/`、`settings.json`），以及各自的作用？
  2. 你能不看 Quick Start，只從 plugin 目錄結構列出它安裝的全部元件、每個元件的作用，以及它在 `settings.json` 裡寫入了什麼嗎？
  3. 你能區分 `claude --plugin-dir` / `--plugin-url` / `/plugin install` 三條安裝路徑的使用時機嗎？
  4. 你能在裝一個新 plugin 之前，列出至少三條供應鏈評估問題與掃描指令嗎？
  5. 若 plugin 與你既有 `.claude/` 設定衝突，你能說出至少兩條排查路徑嗎？
</Check>

## 來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。

<div className="references">
  * \[1] Anthropic, "Create plugins," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/plugins](https://code.claude.com/docs/en/plugins) （截至 2026-06；含目錄結構、manifest schema、4 條安裝路徑、`claude-plugins-official` 與 `claude-community` 兩個市集、`--plugin-dir` / `--plugin-url` 差異）

  * \[2] Anthropic, "Plugins reference," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/plugins-reference](https://code.claude.com/docs/en/plugins-reference) （截至 2026-06；完整 schema、版本管理、private marketplace、subagent 限制三欄位）

  * \[3] Anthropic, "Discover and install plugins," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/discover-plugins](https://code.claude.com/docs/en/discover-plugins) （截至 2026-06；市集瀏覽與安裝流程）

  * \[4] Anthropic, "Create and distribute a plugin marketplace," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/plugin-marketplaces](https://code.claude.com/docs/en/plugin-marketplaces) （截至 2026-06；私有市集與 CI/CD 整合）

  * \[5] Anthropic, "Hooks," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks) （截至 2026-06；plugin `hooks/hooks.json` 與 settings.json 同 schema）
</div>

* 設定層級模型見 [02-1 設定的層級模型](/code-agent/configuration/config-layer-model)。
* Skill 撰寫與 progressive disclosure 見 [04-4 Skill](/code-agent/customization/skills)。
* Subagent frontmatter 見 [04-5 Subagent](/code-agent/customization/subagents)。
* Hook 觸發事件與 command handler 見 [04-6 Hooks](/code-agent/customization/hooks)。
* MCP server 設定見 [04-9 MCP 整合](/code-agent/customization/mcp-integration)。
* 評估框架見 [03-1 如何判斷工具與 Skill 是否適合自己](/code-agent/judgment/fit-evaluation)。
* 供應鏈風險見 [03-3 安全、隱私與供應鏈風險](/code-agent/judgment/security-privacy-supply-chain)。