Claude Plugins Official 原始碼解讀：AI 程式助手的擴展系統設計

Claude Code 作為 AI 編程助手已經廣泛被開發者使用，但多數人只關注「怎麼用」，很少去看它的擴展系統是如何設計的。claude-plugins-official 是 Anthropic 官方維護的 Plugin 目錄倉庫，裡面不僅包含可安裝的 Plugin，更重要的是——它用自身的結構完整展示了一個 AI Agent 擴展系統應該怎麼設計。從 Convention over Configuration 的目錄發現機制、到 Markdown-as-Code 的 Prompt 工程方法，再到多層級的 Hook 攔截架構，這個倉庫是學習「如何設計可擴展 AI Agent 系統」的絕佳範本。

Claude Plugins Official GitHub Repository — 專案原始碼，包含本文解讀的所有 Plugin 設計實作

專案概覽

claude-plugins-official 是 Claude Code 的官方 Plugin 目錄，採用 monorepo 結構管理所有 Plugin。專案不含任何傳統意義上的「應用程式碼」——沒有 main.py，沒有 server.js。整個倉庫由 JSON manifest、Markdown 指令檔和少量 Python/Shell hook 腳本構成。這本身就是一個重要的設計訊號：Plugin 系統的核心是宣告式配置，而非命令式程式碼。

技術棧：JSON（配置）、Markdown（Prompt/指令）、Python（Hook 邏輯）、Shell（Hook 腳本）

架構總覽

claude-plugins-official/
├── .claude-plugin/
│   └── marketplace.json          # 頂層 Marketplace 目錄，定義所有可發現的 Plugin
├── plugins/                      # Anthropic 官方 Plugin（內部維護）
│   ├── example-plugin/           # 參考實作，展示所有擴展點
│   ├── hookify/                  # 唯一包含完整 Python 程式碼的 Plugin
│   ├── feature-dev/              # 多代理工作流 Plugin
│   ├── code-review/              # PR 審查 Plugin
│   ├── pr-review-toolkit/        # 多代理並行 PR 審查
│   ├── security-guidance/        # 安全防護 Hook
│   ├── ralph-loop/               # 自我迭代循環 Plugin
│   ├── plugin-dev/               # Plugin 開發工具包（最複雜的 Skill 結構）
│   ├── frontend-design/          # 前端設計 Skill
│   ├── claude-code-setup/        # 自動化推薦 Skill
│   ├── explanatory-output-style/ # Session Hook 示範
│   ├── commit-commands/          # Git 工作流命令
│   └── ...（12 個 LSP Plugin 等）
└── external_plugins/             # 第三方 Plugin（社群/合作夥伴）
    ├── stripe/                   # 含 Skill + Command 的完整範例
    ├── github/                   # MCP Server 整合
    ├── playwright/               # 瀏覽器自動化
    └── ...（15+ 個外部 Plugin）
Code language: PHP (php)

關鍵觀察：Plugin 系統設計了五種擴展原語（Extension Primitives），分別對應不同的使用情境：

擴展原語	觸發方式	對應目錄	適用場景
Command	使用者主動 `/command`	`commands/`	明確的操作指令
Agent	Claude 自動選擇或產生	`agents/`	專業子任務委派
Skill	Claude 根據情境自動啟用	`skills/`	領域知識注入
Hook	事件觸發的攔截器	`hooks/`	行為守衛與流程控制
MCP Server	工具呼叫整合	`.mcp.json`	外部系統連接

核心設計解析

設計一：Convention over Configuration 的 Auto-Discovery 機制

Plugin 系統最核心的設計決策是自動發現——把目錄結構本身當作配置。只要遵循命名約定，Plugin 的元件就會被自動載入，不需要在任何中央配置檔中註冊。

plugins/example-plugin/.claude-plugin/plugin.json — Plugin 最小 manifest，僅需 name 欄位即可讓整個 Plugin 運作

{
  "name": "example-plugin",
  "description": "A comprehensive example plugin demonstrating all Claude Code extension options including commands, agents, skills, hooks, and MCP servers",
  "author": {
    "name": "Anthropic",
    "email": "[email protected]"
  }
}
Code language: JSON / JSON with Comments (json)

注意這個 plugin.json 裡完全沒有指定任何元件路徑。Claude Code 的載入流程是：

讀取 .claude-plugin/plugin.json 確認 Plugin 存在
掃描 commands/ 目錄中的 .md 檔案 → 自動註冊為 Slash Command
掃描 agents/ 目錄中的 .md 檔案 → 自動註冊為 Subagent
掃描 skills/ 的子目錄中的 SKILL.md → 自動註冊為 Skill
載入 hooks/hooks.json → 註冊 Event Handler
載入 .mcp.json → 啟動 MCP Server

這是典型的 Convention over Configuration 模式。Ruby on Rails 在 Web 框架中推廣了這個理念，而 Claude Code 把它帶到了 AI Agent 擴展系統中。好處是顯而易見的：Plugin 開發者只需要把檔案放到對的位置，就完成了「註冊」。

設計二：Markdown-as-Code 的 Prompt 工程範式

整個 Plugin 系統中最具創新性的設計，是把 Markdown 文件直接當作可執行的 Prompt 程式碼。Command、Agent、Skill 都是 Markdown 檔案，用 YAML Frontmatter 聲明元資料，用 Markdown Body 定義行為指令。

plugins/feature-dev/commands/feature-dev.md — 展示 Markdown 如何定義一個完整的七階段工作流程

Command 的 YAML Frontmatter 格式：

---
description: Guided feature development with codebase understanding and architecture focus
argument-hint: Optional feature description
---
Code language: JavaScript (javascript)

feature-dev 的 Markdown Body 定義了七個完整階段的軟體開發流程：Discovery → Codebase Exploration → Clarifying Questions → Architecture Design → Implementation → Quality Review → Summary。每個階段都有明確的目標、行動步驟、以及跨階段的約束。

這段指令中最值得注意的設計：

## Phase 3: Clarifying Questions
**CRITICAL**: This is one of the most important phases. DO NOT SKIP.

**Actions**:
1. Review the codebase findings and original feature request
2. Identify underspecified aspects: edge cases, error handling, integration points...
3. **Present all questions to the user in a clear, organized list**
4. **Wait for answers before proceeding to architecture design**
Code language: PHP (php)

這不只是 Prompt 文字——它是一個精心設計的工作流狀態機，用自然語言描述了狀態轉換條件（「Wait for answers before proceeding」）、必要約束（「DO NOT SKIP」）、以及每個狀態的輸入輸出。

設計三：Agent Frontmatter 的宣告式能力模型

Agent 的定義同樣使用 Markdown + YAML Frontmatter，但 Frontmatter 中包含了能力約束宣告——指定 Agent 可以使用哪些工具、用哪個模型、甚至顏色標記。

plugins/feature-dev/agents/code-architect.md — 宣告式定義一個架構師 Agent 的能力邊界

---
name: code-architect
description: Designs feature architectures by analyzing existing codebase patterns...
tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput
model: sonnet
color: green
---

這裡的 tools 欄位是關鍵設計——它限制了 Agent 只能使用列出的唯讀工具（注意沒有 Write、Edit、Bash），確保 code-architect 只做分析和設計，不做實作修改。model 欄位允許針對不同任務選擇不同的模型（Haiku 做簡單判斷，Sonnet 做架構分析，Opus 做深度審查）。

相比之下，code-simplifier Agent 則使用了 Opus 模型：

plugins/code-simplifier/agents/code-simplifier.md — 用 Opus 模型的程式碼簡化 Agent

---
name: code-simplifier
description: Simplifies and refines code for clarity, consistency, and maintainability...
model: opus
---

這種以 Frontmatter 宣告能力邊界的方式，本質上是 Capability-Based Security 模式在 AI Agent 系統中的應用——每個 Agent 只被授予完成任務所需的最小權限。

設計四：Skill 的 Context-Triggered 自動注入模式

Skill 是 Plugin 系統中最微妙的擴展點。和 Command（使用者主動觸發）不同，Skill 由 Claude 根據對話情境自動判斷是否啟用。觸發條件完全由 description 欄位中的自然語言定義。

plugins/frontend-design/skills/frontend-design/SKILL.md — 用自然語言觸發條件實現領域知識的動態注入

---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality.
  Use this skill when the user asks to build web components, pages, or applications.
  Generates creative, polished code that avoids generic AI aesthetics.
---
Code language: JavaScript (javascript)

Skill Body 則包含了完整的設計指引，例如前端設計 Skill 明確要求：

NEVER use generic AI-generated aesthetics like overused font families
(Inter, Roboto, Arial, system fonts), cliched color schemes (particularly
purple gradients on white backgrounds), predictable layouts...
Code language: PHP (php)

這個設計理念值得深思：Skill 不是工具呼叫，而是知識注入。當 Claude 判斷當前任務需要前端設計能力時，這段 Markdown 會被注入到 Claude 的上下文中，改變它的行為模式。這是一種「運行時知識裝載」（Runtime Knowledge Loading）機制。

設計五：Hookify 的 Rule Engine 攔截器架構

Hookify 是倉庫中唯一包含完整 Python 實作的 Plugin，展示了如何用 Hook 機制構建一個行為規則引擎。

plugins/hookify/hooks/hooks.json — Hook 事件註冊配置，覆蓋四個生命週期事件

{
  "hooks": {
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.py",
        "timeout": 10
      }]
    }],
    "PostToolUse": [...],
    "Stop": [...],
    "UserPromptSubmit": [...]
  }
}
Code language: JSON / JSON with Comments (json)

四個 Hook 點對應了 Agent 行為的完整生命週期：UserPromptSubmit（使用者輸入時）→ PreToolUse（工具執行前）→ PostToolUse（工具執行後）→ Stop（Agent 嘗試結束時）。

plugins/hookify/core/rule_engine.py — Rule Engine 核心，實作條件匹配和行為決策

Rule Engine 的核心邏輯：

def evaluate_rules(self, rules: List[Rule], input_data: Dict[str, Any]) -> Dict[str, Any]:
    blocking_rules = []
    warning_rules = []

    for rule in rules:
        if self._rule_matches(rule, input_data):
            if rule.action == 'block':
                blocking_rules.append(rule)
            else:
                warning_rules.append(rule)

    # Blocking 規則優先於 Warning 規則
    if blocking_rules:
        messages = [f"**[{r.name}]**\n{r.message}" for r in blocking_rules]
        combined_message = "\n\n".join(messages)
        # 根據不同 Hook 事件類型，回傳不同格式的封鎖回應
        if hook_event in ['PreToolUse', 'PostToolUse']:
            return {
                "hookSpecificOutput": {
                    "hookEventName": hook_event,
                    "permissionDecision": "deny"
                },
                "systemMessage": combined_message
            }
Code language: PHP (php)

這裡的設計決策有兩個值得學習的點：

分層優先級：Block 規則永遠優先於 Warn 規則，無論它們在配置中的順序
事件感知的回應格式：不同 Hook 事件點的回傳格式不同（PreToolUse 用 permissionDecision: deny，Stop 用 decision: block），引擎會根據 hook_event_name 自動選擇正確的回應結構

plugins/hookify/core/config_loader.py — 規則載入器，展示 Markdown-as-Config 的解析機制

規則的定義方式同樣是 Markdown 檔案：

---
name: block-dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---

⚠️ **Dangerous rm command detected!**
Please verify the path is correct.
Code language: JavaScript (javascript)

Config Loader 自行實作了一個簡單的 YAML Frontmatter 解析器，將 Markdown 規則檔案解析為 Rule dataclass。這些 .local.md 規則檔案放在專案的 .claude/ 目錄中，每次 Hook 觸發時動態載入——不需要重啟 Claude Code。

設計六：Security Hook 的 Pattern-Based 防護策略

Security Guidance Plugin 展示了如何用 Hook 實作「安全護欄」（Safety Guardrail）。

plugins/security-guidance/hooks/security_reminder_hook.py — 基於模式匹配的安全提醒 Hook

SECURITY_PATTERNS = [
    {
        "ruleName": "github_actions_workflow",
        "path_check": lambda path: ".github/workflows/" in path
        and (path.endswith(".yml") or path.endswith(".yaml")),
        "reminder": """You are editing a GitHub Actions workflow file. Be aware of these security risks:
1. **Command Injection**: Never use untrusted input directly in run: commands...
2. **Use environment variables**: Instead of ${{ github.event.issue.title }}..."""
    },
    {
        "ruleName": "child_process_exec",
        "substrings": ["child_process.exec", "exec(", "execSync("],
        "reminder": """⚠️ Security Warning: Using child_process.exec() can lead to command injection...
This codebase provides a safer alternative: src/utils/execFileNoThrow.ts"""
    },
]
Code language: PHP (php)

三個值得注意的設計細節：

Session-Scoped 去重：每個安全提醒在同一 session 中只顯示一次，用 warning_key = f"{file_path}-{rule_name}" 追蹤已顯示的警告
Exit Code 語義：sys.exit(0) 允許操作繼續，sys.exit(2) 封鎖工具執行——Hook 的控制語義完全透過 exit code 表達
Graceful Degradation：所有異常都被捕獲並允許操作繼續（sys.exit(0)），確保安全 Hook 的故障不會阻斷開發者的工作流

設計七：多代理協作的 Orchestration 模式

code-review Plugin 展示了精心設計的多 Agent 協作流程——不是簡單地並行跑多個 Agent，而是設計了一個包含資格檢查、並行審查、信心評分、結果過濾的完整 pipeline。

plugins/code-review/commands/code-review.md — 八步驟的多代理 PR 審查 pipeline

1. Use a Haiku agent to check if the pull request (a) is closed, (b) is a draft,
   (c) does not need a code review, or (d) already has a code review from you
2. Use another Haiku agent to give you a list of CLAUDE.md files
3. Use a Haiku agent to view the pull request and return a summary
4. Launch 5 parallel Sonnet agents to independently code review the change:
   a. Agent #1: Audit CLAUDE.md compliance
   b. Agent #2: Shallow scan for obvious bugs
   c. Agent #3: Read git blame and history for historical context bugs
   d. Agent #4: Read previous PRs for recurring comments
   e. Agent #5: Check code comments compliance
5. For each issue, launch a parallel Haiku agent that scores confidence (0-100)
6. Filter out any issues with a score less than 80
7. Use a Haiku agent to repeat eligibility check
8. Comment back on the pull request with results
Code language: CSS (css)

這個流程體現了幾個關鍵的 Orchestration 設計模式：

Model-Appropriate 任務分派：Haiku 做簡單判斷（資格檢查、信心評分），Sonnet 做深度分析（程式碼審查），成本效益最佳化
Confidence-Based 過濾：不是所有 Agent 發現的問題都輸出，而是經過二次 Agent 評分，只保留 80 分以上的高信心結果
False Positive 意識：指令中明確列出了十多種 false positive 模式，訓練 Agent 避免過度報告

設計八：Ralph Loop 的 Stop Hook 持續循環技術

Ralph Loop Plugin 展示了一個非常巧妙的技術：利用 Stop Hook 阻止 Agent 退出，實現自我迭代循環。

plugins/ralph-loop/hooks/stop-hook.sh — 用 Stop Hook 實作 Agent 自我循環迭代

核心機制：

# 從 transcript 讀取上一次 Agent 的輸出
LAST_OUTPUT=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1 | jq -r '
  .message.content | map(select(.type == "text")) | map(.text) | join("\n")')

# 檢查 completion promise — 只有當 Agent 輸出了正確的 promise 標記才允許結束
if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
    echo "✅ Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>"
    rm "$RALPH_STATE_FILE"
    exit 0
fi

# 否則，封鎖停止並餵入原始 prompt 繼續循環
jq -n --arg prompt "$PROMPT_TEXT" --arg msg "$SYSTEM_MSG" '{
    "decision": "block",
    "reason": $prompt,
    "systemMessage": $msg
}'
Code language: PHP (php)

設計精華在於 Completion Promise 機制——Agent 不是自己決定何時結束，而是必須在輸出中包含一個特定的 <promise> 標記，並且這個標記必須與預設的承諾完全一致。指令中甚至強調：

CRITICAL RULE: If a completion promise is set, you may ONLY output it when
the statement is completely and unequivocally TRUE. Do not output false
promises to escape the loop.
Code language: PHP (php)

這是一種外部終止條件（External Termination Condition）設計——Agent 的循環控制權不在 Agent 自己手上，而是由 Hook 系統根據可驗證的條件來決定。

設計九：Marketplace 目錄的雙軌分發策略

頂層的 marketplace.json 展示了一個巧妙的 Plugin 分發設計——用同一個 JSON 檔案管理兩種完全不同的分發策略。

.claude-plugin/marketplace.json — Marketplace 目錄，管理所有可發現 Plugin 的 metadata

{
  "plugins": [
    {
      "name": "typescript-lsp",
      "source": "./plugins/typescript-lsp",
      "category": "development",
      "strict": false,
      "lspServers": {
        "typescript": {
          "command": "typescript-language-server",
          "args": ["--stdio"],
          "extensionToLanguage": {
            ".ts": "typescript", ".tsx": "typescriptreact"
          }
        }
      }
    },
    {
      "name": "figma",
      "source": {
        "source": "url",
        "url": "https://github.com/figma/mcp-server-guide.git"
      },
      "homepage": "https://github.com/figma/mcp-server-guide"
    }
  ]
}
Code language: JSON / JSON with Comments (json)

兩種 source 格式：

本地路徑 "./plugins/..." — 從此倉庫直接安裝，由 Anthropic 完全控制
遠端 URL { "source": "url", "url": "https://..." } — 從第三方 Git 倉庫安裝，由社群維護

同時注意 LSP Plugin 的配置：它們不需要 commands/、agents/ 等目錄，直接在 marketplace.json 中用 lspServers 欄位宣告——因為 LSP 整合只需要指定 command 和語言映射，不需要任何 Prompt 指令。

設計十：Hook 注入 System Message 改變 Agent 行為

Explanatory Output Style Plugin 展示了一個精巧的 Hook 用法——透過 SessionStart Hook 注入額外的 System Message，在不修改任何程式碼的情況下改變 Claude 的整體行為風格。

plugins/explanatory-output-style/hooks-handlers/session-start.sh — 用 SessionStart Hook 注入教學模式指令

cat << 'EOF'
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "You are in 'explanatory' output style mode...
    In order to encourage learning, before and after writing code, always provide
    brief educational explanations using:
    \"`★ Insight ─────────────────────────────────────`\n
    [2-3 key educational points]\n
    `─────────────────────────────────────────────────`\""
  }
}
EOF
Code language: PHP (php)

這個設計模式非常強大：Hook 不只能攔截和判斷，還能注入 context。透過 additionalContext 欄位，任何 Hook 都可以在不修改 Claude 核心行為的情況下，動態地為 session 加入新的行為指引。

Prompt 設計解讀

這個倉庫最有價值的部分之一是其中包含的 Prompt 設計模式。以下是幾個值得深入研究的 Prompt 工程技巧：

Agent 創建系統 Prompt 的結構化設計

plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md — Agent 生成的元 Prompt，展示如何設計「生成 Agent 的 Agent」

此系統 Prompt 是一個「Meta Prompt」——生成其他 Agent 的 Agent。它定義了六步流程：Extract Core Intent → Design Expert Persona → Architect Instructions → Optimize for Performance → Create Identifier → Example Descriptions。輸出是結構化的 JSON：

{
  "identifier": "描述性識別碼",
  "whenToUse": "觸發條件描述",
  "systemPrompt": "完整的系統指令"
}
Code language: JSON / JSON with Comments (json)

Silent Failure Hunter 的角色設定技巧

plugins/pr-review-toolkit/agents/silent-failure-hunter.md — 展示如何用人格設定驅動 Agent 行為

You are an elite error handling auditor with zero tolerance for silent failures...

## Core Principles
1. **Silent failures are unacceptable** - Any error without proper logging is a critical defect
2. **Users deserve actionable feedback** - Every error message must tell users what to do
Code language: PHP (php)

注意 Prompt 中使用了「non-negotiable rules」和「zero tolerance」等強語氣詞彙。這不是隨意的語言選擇——這是 Prompt 工程中的角色強化技巧，確保 Agent 在面對模糊情境時偏向嚴格而非寬鬆。

Stripe Skill 的領域專家知識注入

external_plugins/stripe/skills/stripe-best-practices/SKILL.md — 展示如何把領域知識結構化為 Skill

Stripe Skill 的 Prompt 不是泛泛的指引，而是包含了大量具體的 API 建議和明確的禁止項：

Never recommend the Charges API...
Never recommend the legacy Card Element...
You must not call deprecated API endpoints such as the Sources API...
Code language: JavaScript (javascript)

這是 Skill 設計的最佳實踐：不是告訴 Agent「要小心」，而是明確列出所有禁止項和推薦替代方案。

設計理念萃取

Convention over Configuration 降低認知負擔 — Plugin 系統讓開發者只需要把檔案放到對的位置，就完成了功能註冊。對於 AI Agent 的擴展系統設計，「目錄結構即配置」比「中央設定檔」更直覺，也更不容易出錯。這個理念可以應用到任何需要第三方擴展的系統中。
Markdown-as-Code 是 Prompt 工程的最佳載體 — 用 Markdown 定義 Agent 行為，同時兼具可讀性、版本控制友好和結構化（YAML Frontmatter）的優點。如果你正在構建自己的 Agent 系統，考慮用 Markdown 而非 JSON 或 YAML 來定義 Prompt 和工作流——它對人類和 AI 都更友好。
五種擴展原語覆蓋了 Agent 行為的所有面向 — Command（使用者觸發）、Agent（任務委派）、Skill（知識注入）、Hook（行為攔截）、MCP（工具整合），這五個維度幾乎覆蓋了 AI Agent 系統所有可能的擴展需求。設計自己的擴展系統時，可以用這個分類框架來檢驗是否有遺漏。
Capability-Based Security 在 AI Agent 中至關重要 — 透過 Frontmatter 中的 tools 和 model 欄位限制每個 Agent 的能力邊界，是 Principle of Least Privilege 在 AI 系統中的直接應用。在多 Agent 系統中，不受限的 Agent 是一個安全風險。
Hook 不只是攔截器，更是行為注入器 — Explanatory Output Style 和 Ralph Loop 證明了 Hook 的潛力遠超「阻止壞行為」。Hook 可以注入 context、改變行為模式、甚至控制 Agent 的生命週期。設計 Hook 系統時，考慮 additionalContext 這樣的正向注入能力，而非僅僅是 allow/deny 的二元決策。

延伸思考

如果你正在建構自己的 AI Agent 系統或 Plugin 架構，有幾個方向可以直接借鏡：

為你的 Agent 設計擴展原語：參考 Claude Code 的五種原語，思考你的系統需要哪些擴展點。不需要全部實作，但要明確分類——「使用者主動觸發」和「AI 自動判斷」是完全不同的設計空間。
用 Markdown 管理 Prompt：如果你的 Agent 系統有多個 Prompt 或行為指令，把它們從程式碼中抽出來，用 Markdown 檔案管理。不僅版本控制更清晰，也讓非工程師（Prompt Designer、Product Manager）可以直接參與。
設計 Hook 系統時考慮雙向性：不只做 allow/deny 的攔截，也提供 context 注入的能力。Claude Code 的 systemMessage 和 additionalContext 欄位證明了這種雙向設計的價值。
多 Agent 協作需要 Confidence Scoring：不要直接輸出所有 Agent 的結果——加一層 Confidence 評分和過濾。Code Review Plugin 的 0-100 分評分 + 80 分閾值的設計，是一個可以直接複用的模式。

Vibe Coding：把觀念變成程式碼

以下是你可以直接給 AI 的 prompt 指令，將本文介紹的設計觀念應用到你的專案中：

Convention over Configuration 的 Auto-Discovery 機制

場景：你正在設計一個支援擴展的系統（Plugin、Module、Middleware），需要讓第三方開發者能方便地新增功能，而不需要手動在設定檔中註冊。

給 AI 的指令：

我的專案需要一個 Plugin/Module 擴展系統。請參考 Convention over Configuration 設計模式，設計一個 auto-discovery 載入機制：

1. 定義一個固定的目錄結構約定（例如 plugins/[plugin-name]/ 下放什麼檔案代表什麼功能）
2. 實作一個 loader，它掃描目錄結構並自動註冊符合約定的元件，不需要中央設定檔
3. 每個 Plugin 只需要一個最小的 manifest 檔（例如 plugin.json 只需 name 欄位）
4. 提供一個範例 Plugin 展示完整的目錄約定

我的技術棧是 [填入你的語言/框架]，目前的專案結構是 [貼上你的目錄樹]。

效果：AI 會為你設計一套完整的目錄約定和自動掃描載入邏輯，讓新 Plugin 只需要把檔案放到對的位置就能被系統發現，無需修改任何其他檔案。

Markdown-as-Code 的 Prompt 工程範式

場景：你的 AI Agent 專案中散落著大量 Prompt，有的硬寫在程式碼裡，有的放在 YAML 或 JSON 中，難以管理和版本控制。

給 AI 的指令：

我想把專案中的 AI Prompt 重構為 Markdown-as-Code 格式。請幫我：

1. 設計一個 Markdown 模板，用 YAML Frontmatter 聲明 metadata（名稱、描述、觸發條件、模型選擇等），Markdown Body 定義實際的 Prompt 指令
2. 實作一個 Markdown Prompt Loader，能解析 YAML Frontmatter 和 Body，轉換成可用的 Prompt 物件
3. 把以下現有的 Prompt 轉換成這個格式：[貼上你的現有 Prompt]

參考格式：用 --- 包裹 YAML Frontmatter（包含 description、model、tools 等欄位），Body 部分用 Markdown 標題分段描述工作流步驟。

效果：AI 會產出一套 Markdown Prompt 管理方案，讓你的 Prompt 像程式碼一樣有版本控制、可讀性高，也方便非工程師直接編輯。

Capability-Based Security 的宣告式能力約束

場景：你的多 Agent 系統中，某些 Agent 擁有過多的權限（例如可以讀寫檔案、執行命令），你需要為每個 Agent 設定最小權限。

給 AI 的指令：

我正在建構一個多 Agent 系統，需要實作 Capability-Based Security。請幫我：

1. 審查以下 Agent 定義，列出每個 Agent 實際需要的最小工具/權限集合：[貼上你的 Agent 定義或描述]
2. 設計一個宣告式的能力約束機制，讓每個 Agent 在定義時就聲明它能用哪些工具（類似 Claude Code Plugin 的 tools 欄位），系統在執行時強制限制
3. 區分「唯讀 Agent」（只能用 Read、Search 等工具）和「讀寫 Agent」（可以用 Write、Edit、Execute 等工具），並根據任務性質分配

遵循 Principle of Least Privilege 原則：每個 Agent 只被授予完成任務所需的最小權限。

效果：AI 會分析你的 Agent 並產出權限矩陣，設計一套宣告式的能力限制系統，確保每個 Agent 在其安全邊界內運作。

Hook 系統的雙向設計（攔截 + 注入）

場景：你想為現有的 AI Agent 或自動化流程加上一套 Hook 系統，不只是做允許/拒絕的攔截，還要能動態注入上下文或改變行為。

給 AI 的指令：

我需要為我的 [Agent 系統/自動化流程] 設計一個 Hook 系統。請參考 Claude Code 的 Hook 架構，實作以下功能：

1. 定義生命週期事件點：至少包含 BeforeAction（執行前攔截）、AfterAction（執行後處理）、OnStart（啟動時）、OnStop（結束時）
2. 每個 Hook 可以回傳三種決策：allow（允許繼續）、deny（封鎖操作）、或 inject（注入額外上下文/指令）
3. Hook 回傳結構中包含 systemMessage（注入到 Agent 的系統訊息）和 additionalContext（附加上下文）欄位
4. 支援從設定檔動態載入 Hook，不需重啟系統

技術棧：[你的語言/框架]。請提供完整的 Hook 介面定義和一個範例 Hook。

效果：AI 會設計一套完整的 Hook 系統，包含事件定義、回傳格式、動態載入機制，讓你能同時攔截不良行為和注入有用的上下文資訊。

多代理協作的 Confidence-Based 過濾

場景：你有多個 Agent 各自產出分析結果（例如 Code Review、文件審查、安全掃描），但直接合併所有結果會產生大量 false positive，需要一個品質過濾機制。

給 AI 的指令：

我有多個 Agent 會各自產出分析結果，需要設計一個 Confidence-Based 過濾 pipeline。請幫我：

1. 設計一個兩階段的多代理協作流程：
– 第一階段：多個專業 Agent 並行分析，各自產出發現清單
– 第二階段：一個評分 Agent 對每個發現給出 0-100 的信心分數，只保留超過閾值（例如 80 分）的結果
2. 參考 Claude Code code-review Plugin 的設計：用較輕量的模型做簡單判斷和評分，用較強的模型做深度分析
3. 在評分 Agent 的 Prompt 中加入常見的 false positive 模式清單，讓它學會過濾誤報

我的場景是：[描述你的多 Agent 分析場景]

效果：AI 會產出一個完整的兩階段 pipeline 架構，包含並行分析的 Agent Prompt、評分 Agent 的 Prompt（含 false positive 清單）、以及結果過濾邏輯。

Claude Plugins Official 原始碼解讀：AI 程式助手的擴展系統設計

專案概覽

架構總覽

核心設計解析

設計一：Convention over Configuration 的 Auto-Discovery 機制

設計二：Markdown-as-Code 的 Prompt 工程範式

設計三：Agent Frontmatter 的宣告式能力模型

設計四：Skill 的 Context-Triggered 自動注入模式

設計五：Hookify 的 Rule Engine 攔截器架構

設計六：Security Hook 的 Pattern-Based 防護策略

設計七：多代理協作的 Orchestration 模式

設計八：Ralph Loop 的 Stop Hook 持續循環技術

設計九：Marketplace 目錄的雙軌分發策略

設計十：Hook 注入 System Message 改變 Agent 行為

Prompt 設計解讀

Agent 創建系統 Prompt 的結構化設計

Silent Failure Hunter 的角色設定技巧

Stripe Skill 的領域專家知識注入

設計理念萃取

延伸思考

Vibe Coding：把觀念變成程式碼

Convention over Configuration 的 Auto-Discovery 機制

Markdown-as-Code 的 Prompt 工程範式

Capability-Based Security 的宣告式能力約束

Hook 系統的雙向設計（攔截 + 注入）

多代理協作的 Confidence-Based 過濾

延伸閱讀

發佈留言取消回覆

專案概覽

架構總覽

核心設計解析

設計一：Convention over Configuration 的 Auto-Discovery 機制

設計二：Markdown-as-Code 的 Prompt 工程範式

設計三：Agent Frontmatter 的宣告式能力模型

設計四：Skill 的 Context-Triggered 自動注入模式

設計五：Hookify 的 Rule Engine 攔截器架構

設計六：Security Hook 的 Pattern-Based 防護策略

設計七：多代理協作的 Orchestration 模式

設計八：Ralph Loop 的 Stop Hook 持續循環技術

設計九：Marketplace 目錄的雙軌分發策略

設計十：Hook 注入 System Message 改變 Agent 行為

Prompt 設計解讀

Agent 創建系統 Prompt 的結構化設計

Silent Failure Hunter 的角色設定技巧

Stripe Skill 的領域專家知識注入

設計理念萃取

延伸思考

Vibe Coding：把觀念變成程式碼

Convention over Configuration 的 Auto-Discovery 機制

Markdown-as-Code 的 Prompt 工程範式

Capability-Based Security 的宣告式能力約束

Hook 系統的雙向設計（攔截 + 注入）

多代理協作的 Confidence-Based 過濾

延伸閱讀

相關文章

NanoClaw 原始碼解讀：用極簡架構打造安全的個人 AI 助理

nanobot 原始碼解讀：用 3,400 行程式碼重建一個完整 AI Agent 框架

Anthropic Skills 原始碼解讀：如何設計 AI Agent 的可插拔能力系統

發佈留言取消回覆