claude-plugins-official 詳細教學

對應 repo: https://github.com/anthropics/claude-plugins-official（21.6k stars / 2.6k forks / 203 plugins，截至 2026-05-21）

1. 專案定位

1.1 它是什麼

Anthropic 官方維運的 Claude Code plugin (CC; 插件) 中央目錄。203 個 plugin 全部由一份 marketplace.json 管理，配上 7 個 CI workflow（其中最關鍵的是「Claude 自動跑資安審查」），實現「PR 進來 → AI 審查通過 → 才能合併」的端到端 plugin 治理 pipeline。

1.2 它解決什麼問題

• plugin 發現：使用者在 Claude Code 內 /plugin > Discover 直接從這個 repo 拉清單
• plugin 安裝：/plugin install <name>@claude-plugins-official 一行裝
• plugin 信任：每個 plugin / 每次 SHA bump 都會走 AI 自動審查（不只「不是 malware」，更是「資料蒐集範圍合理」）
• plugin 自動更新：每晚 cron 自動 bump 所有外部 plugin 的 SHA pin，失敗自動回退

1.3 與其他 plugin marketplace 的差異

1.4 適合誰用

• Claude Code 使用者：想找信任度最高的 plugin 來源
• plugin 開發者：想把自己的 plugin 提交給官方收錄（透過 submission form）
• 想自製 marketplace 的人：直接抄 .claude-plugin/marketplace.json 的 schema
• DevSecOps 工程師：想在自家 repo 實作「Claude 自動審查 PR」的人，這個 repo 的 .github/workflows/scan-plugins.yml 是最完整的開源範本

2. 安裝指南

2.1 使用既有 plugin（最常見用法）

你不需要 clone 這個 repo。在 Claude Code 直接：

 1# 1. 列出全部 plugin
 2/plugin
 3
 4# 2. 從這個 marketplace 安裝
 5/plugin install code-review@claude-plugins-official
 6/plugin install feature-dev@claude-plugins-official
 7/plugin install hookify@claude-plugins-official
 8
 9# 3. 瀏覽分類
10/plugin > Discover

2.2 本地探索（想看原始 plugin 碼）

 1# 淺 clone（只要 metadata + 內部 plugin 原始碼）
 2git clone --depth 1 https://github.com/anthropics/claude-plugins-official
 3cd claude-plugins-official
 4
 5# 看完整 marketplace（203 個 plugin）
 6cat .claude-plugin/marketplace.json | jq '.plugins[] | {name, category, author: .author.name}'
 7
 8# 看 example plugin 結構
 9ls plugins/example-plugin/
10# .claude-plugin/plugin.json  .mcp.json  commands/  skills/  README.md  LICENSE

2.3 自製 marketplace.json（fork 模式）

 1# 把這個 repo 當 template
 2git clone https://github.com/anthropics/claude-plugins-official my-marketplace
 3cd my-marketplace
 4
 5# 改 marketplace.json：保留 schema、清掉 plugins list
 6jq '. + {plugins: []}' .claude-plugin/marketplace.json > .claude-plugin/marketplace.new.json
 7mv .claude-plugin/marketplace.{new.,}json
 8
 9# 加自己的 plugin 進去
10# 在 Claude Code 內：/plugin marketplace add <你的 repo URL>

flowchart TD
    A[使用者在 Claude Code] -->|/plugin install X@claude-plugins-official| B[拉 marketplace.json]
    B --> C{source 類型}
    C -->|local: ./plugins/X| D[直接從本 repo 取]
    C -->|git-subdir: 外部 repo| E[clone 指定 sha + path]
    C -->|url: 直連| F[下載 plugin 包]
    D --> G[本地安裝 .claude/plugins/X]
    E --> G
    F --> G
    G --> H[plugin 可用]

3. 核心架構解析

3.1 三層結構

graph TB
    subgraph "Layer 1 — 中央目錄"
        M[.claude-plugin/marketplace.json
2701 行 / 203 plugins]
    end
    subgraph "Layer 2 — 三種 source 類型"
        L1[local: ./plugins/X
36 個內部 plugin]
        L2[git-subdir: 外部 repo
47 個夥伴 plugin]
        L3[url: 直連 URL
104 個 + github 2 個]
    end
    subgraph "Layer 3 — CI 治理 (7 workflows)"
        W1[scan-plugins.yml
380 行 / Claude 審查]
        W2[bump-plugin-shas.yml
每晚自動 bump SHA]
        W3[revert-failed-bumps.yml
失敗回退]
        W4[check-mcp-urls.yml]
        W5[validate-plugins.yml]
        W6[validate-frontmatter.yml]
        W7[close-external-prs.yml]
    end
    M --> L1
    M --> L2
    M --> L3
    L1 -. PR 觸發 .-> W1
    L2 -. PR 觸發 .-> W1
    L3 -. PR 觸發 .-> W1
    W2 -. 自動產生 PR .-> W1
    W1 -- 失敗 --> W3

3.2 marketplace.json schema

每筆 plugin 至少要有 name、description、source；其他欄位都選填。三種 source 形態：

 1// (A) 內部 plugin — 在本 repo /plugins 底下
 2{
 3  "name": "code-review",
 4  "source": "./plugins/code-review"
 5}
 6
 7// (B) git-subdir — 從別人的 repo 取一個子目錄
 8{
 9  "name": "42crunch-api-security-testing",
10  "source": {
11    "source": "git-subdir",
12    "url": "https://github.com/42Crunch-AI/claude-plugins.git",
13    "path": "plugins/api-security-testing",
14    "ref": "v1.5.5",
15    "sha": "faf5305385de8afed9468904e8639be737aff39e"   // SHA pinning，每晚 auto-bump
16  }
17}
18
19// (C) url — 直接從 URL 抓 plugin 包
20{
21  "name": "snowflake-cortex-code",
22  "source": {
23    "source": "url",
24    "url": "https://example.com/plugin-bundle.tgz"
25  }
26}

設計意義：SHA pinning 而非 ref pinning，是「即使對方 force-push，本地裝的 plugin 仍是 audit 過的那個 SHA」的保證。

3.3 單一 plugin 結構（以 example-plugin 為例）

 1plugins/example-plugin/
 2├── .claude-plugin/
 3│   └── plugin.json              # 必要（plugin metadata）
 4├── .mcp.json                    # 選填（MCP server 設定）
 5├── commands/                    # 選填（slash 命令）
 6│   └── example-command.md
 7├── skills/                      # 選填（skill 定義）
 8│   ├── example-skill/SKILL.md
 9│   └── example-command/SKILL.md
10├── agents/                      # 選填（agent 定義）
11├── hooks/                       # 選填（hooks.json + 對應檔）
12├── README.md                    # 強烈建議
13└── LICENSE                      # 強烈建議

3.4 CI 治理 pipeline（資安 + 自動化）

sequenceDiagram
    participant Dev as 開發者
    participant Bot as claude[bot]
    participant Scan as scan-plugins.yml
(380 lines)
    participant Claude as Claude API
    participant Cache as Verdict Cache
(per-SHA)
    participant Revert as revert-failed-bumps.yml

    Note over Bot: 每晚 cron
    Bot->>Scan: 自動產生 SHA bump PR
    Scan->>Cache: 查 (plugin, sha) verdict
    alt Cache miss
        Scan->>Claude: 跑 .github/policy/prompt.md
        Claude-->>Scan: passes: true/false
has_broad_scope_hooks
has_undisclosed_telemetry
        Scan->>Cache: 存 verdict (30 day TTL)
    else Cache hit
        Cache-->>Scan: 直接取
    end
    alt passes: true
        Scan-->>Bot: ✅ 合併
    else passes: false
        Scan-->>Revert: 觸發
        Revert->>Bot: 從 PR 移除失敗 entry
        Revert->>Scan: 重新跑（剩下 cached-pass 秒過）
    end

關鍵設計：

• per-SHA cache：同一個 plugin 同一個 SHA 不重審，省 ~90 秒 / 個 Claude time
• policy hash 入 cache key：prompt 改了會自動 invalidate 所有 verdict
• 單壞蛋不擋整 PR：revert-failed-bumps.yml 自動把失敗的 entry 移除，不需要人介入

4. Helper Scripts 詳細用法

4.1 .github/scripts/discover_bumps.py

Python 腳本，偵測有哪些 plugin 的 upstream 出現新 commit / tag，產生 bump candidates。重點片段：

1import subprocess
2# 對每個 git-subdir plugin 跑 git ls-remote 抓 HEAD SHA
3r = subprocess.run(
4    ["git", "ls-remote", url, ref],
5    capture_output=True, text=True, check=True
6)
7new_sha = r.stdout.split()[0]
8# 比較 marketplace.json 裡的舊 SHA → 不一樣就加入 bump list

每晚由 bump-plugin-shas.yml 觸發；輸出餵給 gh pr create 產生自動 PR。

4.2 .github/scripts/validate-frontmatter.ts

TypeScript 校驗器，跑在 validate-frontmatter.yml 內，檢查每個 plugin 的 commands/*.md / skills/*/SKILL.md / agents/*.md 的 YAML frontmatter 是否符合 schema。

4.3 .github/policy/prompt.md（最值得抄的檔案）

長篇 system prompt，告訴 Claude：

1. Part 1 — 基線安全：找惡意碼、prompt injection、deceptive functionality
2. Part 2 — Hook scope 嚴格審查：列出所有 hooks，看是不是「無條件每個 session 都跑」、看是否做未揭露的 outbound call
3. Part 3 — 描述對齊：plugin.json description 跟實際行為要對得上

輸出 JSON verdict（schema.json 約束）：

1{
2  "passes": true,
3  "has_broad_scope_hooks": false,
4  "has_undisclosed_telemetry": false,
5  "reasoning": "..."
6}

移植建議：任何「使用者貢獻內容」的 repo（例如 awesome-list、template gallery、prompts garden），都可以直接 fork 這個 prompt.md 改幾行做 PR 守門。

4.4 Workflow 行數一覽

5. 應用場景

6. 資安掃描報告

掃描範圍：.github/scripts/、.github/policy/、plugins/example-plugin/、external_plugins/*/server.ts、marketplace.json 中的 source URL。

綜合燈號：🟢 對 repo 本體 / 🟡 對「裝下來的第三方 plugin」（治理機制健全但仍建議使用者自審）

重點建議：

• 安裝 external_plugins 前逐一檢視 .mcp.json 連到哪個 server
• 信任 Anthropic 自家 36 個 /plugins/ 高於第三方 152 個
• 若自家做 marketplace，務必 fork scan-plugins.yml 與 policy/prompt.md 建立同等審查層

7. FAQ

Q1：本 repo 跟 anthropics/financial-services 是什麼關係？ A：FS 是「12 個垂直領域 plugin 包」放在自家 repo；本 repo 是「全 Anthropic 生態的中央目錄」會收 FS 也會收所有第三方。可以把本 repo 理解為「App Store 目錄」，FS 是「Anthropic 自家上架的一組 app」。

Q2：為什麼 plugin 數一直在跳？昨天 178 今天 203？ A：每晚 cron 跑 bump-plugin-shas.yml，常常一晚加 20+ 個外部 plugin / bump 20+ 個 SHA；只要過 AI 審查就會合進來。

Q3：可以裝沒有過 AI 審查的 plugin 嗎？ A：可以——任何 GitHub repo + plugin.json 都能在 Claude Code 用 /plugin marketplace add <URL> 加進去。差別是本 repo 提供「過 AI 審查」這層信任，自己加的 marketplace 沒有。

Q4：plugin 開發者如何提交？ A：填 https://clau.de/plugin-directory-submission；不要直接開 PR — close-external-prs.yml 會自動關。

Q5：本 repo 為什麼沒 LICENSE？ A：因為 repo 本身只是目錄；每個 plugin 自帶 LICENSE。example-plugin 自己有 LICENSE，可以當參考。

Q6：SHA-pinning 是怎麼運作的？ A：marketplace.json 把每個外部 plugin 的 commit SHA 寫死；安裝時走 git checkout <sha> 取那一份具體版本。upstream 即使 rebase / force-push / 刪 branch，已寫入 marketplace 的 SHA 仍可從 GitHub 取得（GitHub 保留 dangling commit）。

Q7：external_plugins 的 server.ts 是怎麼跑的？ A：用 bun 跑（看 bun.lock 與 package.json）。每個 MCP server 都是獨立的 Node-like process，透過 .mcp.json 的 command / args 啟動。

8. 進階技巧

8.1 寫一個只有 hooks 的 plugin

看 plugins/security-guidance/：

1security-guidance/
2├── hooks/
3│   ├── hooks.json
4│   └── <hook scripts>
5└── LICENSE

連 .claude-plugin/plugin.json 都不一定需要（marketplace.json 已有 metadata）。

8.2 寫一個 LSP plugin

看 plugins/typescript-lsp/、plugins/pyright-lsp/：通常只需要 .mcp.json 串接 LSP server，零原始碼。

8.3 寫一個含 MCP server 的完整 plugin

看 external_plugins/discord/：

• server.ts — MCP server 邏輯（用 @modelcontextprotocol/sdk）
• .mcp.json — 怎麼啟動（bun run server.ts）
• package.json + bun.lock — 依賴
• ACCESS.md — 文件化所需權限
• README.md — 使用者文件

8.4 寫一個過 AI 審查的 plugin

看 .github/policy/prompt.md 第二段「Part 2 — Hook scope and disclosure」，主要審查點：

1. Hook 是否 gated（只在相關專案觸發，例如「只在有 vercel.json 的目錄」）
2. Hook 是否有未揭露的 outbound call
3. plugin.json description 是否清楚說明會做什麼

按這三點寫 plugin，AI 審查就會過。

8.5 在內部 repo 重現 AI 自動審查機制

最小可行做法：

1# 1. 把這四個檔搬到自家 repo
2cp .github/workflows/scan-plugins.yml      <your-repo>/.github/workflows/
3cp .github/policy/prompt.md                <your-repo>/.github/policy/
4cp .github/policy/schema.json              <your-repo>/.github/policy/
5cp .github/scripts/discover_bumps.py       <your-repo>/.github/scripts/
6
7# 2. 改 prompt.md 第一段「Review the plugin files...」→ 換成你的審查對象
8# 3. 改 workflow 的 MARKETPLACE env var → 指向你的中央檔
9# 4. 設好 ANTHROPIC_API_KEY 在 GitHub Actions secrets

30 分鐘內可以做出「PR 進來 → Claude 自動審查 → 過了才能合併」。

9. 整合進其他工作流

10. 重點摘要 Checklist

• 21.6k stars / 2.6k forks / 203 plugins / Apache-2.0 各 plugin 自帶
• 三種 source：local (50) / git-subdir (47) / url (104) + github (2)
• CI workflows = 7 個（scan-plugins.yml = 380 行為核心）
• AI 自動審查 = policy/prompt.md + Claude API + per-SHA verdict cache
• 自動 SHA bump → 失敗自動回退（閉環）
• plugin.json 結構 = 必要 name + description + source；選填 author / category / homepage / commands / skills / agents / hooks / .mcp.json
• Anthropic 自家 36 plugin（development / security / productivity 三類為主）
• 第三方 15 個 external_plugins（Asana / Linear / Discord / GitHub Copilot 等 MCP server）
• 第三方 152 個 git-subdir/url（透過 AI 審查 + SHA pin 才收進來）
• 資安綜合燈號：🟢 repo 本體 / 🟡 第三方 plugin（建議裝前自審 .mcp.json）

11. 進一步閱讀

• 官方 plugins 文件：https://code.claude.com/docs/en/plugins
• 提交 plugin：https://clau.de/plugin-directory-submission
• Anthropic Software Directory Policy：https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy
• Anthropic Acceptable Use Policy：https://www.anthropic.com/legal/aup
• 對應姊妹專案 anthropics/financial-services（垂直版）：https://github.com/anthropics/financial-services
• 本知識庫先前 gh-save：inbox/2026-05-20-github-anthropics-financial-services.md