ARCHITECTURE Skill / Domain / Tool

Skill / Domain / Tool
工作流程、方法與工具如何分工

REVIT_MCP 的核心架構：把 94 個 Domain、239 個工具按職責分開：Skill 管「流程」（怎麼編排步驟）、Domain 管「方法」（法規、公式、邊界案例）、Tool 管「操作」（真正去查或改 Revit）。CLAUDE.md 另外記載專案維護規則與多 AI Client 共用指引，不屬於這三種職責。本頁同時澄清「MCP ≠ Skill」的常見誤解。

CLARIFICATION · 廚房與食譜

MCP ≠ Skill：官方定義與比喻

社群常爭論「Skill 會不會取代 MCP」。答案是不會——MCP 是廚房（給 AI 能力），Skill 是食譜（給 AI 知識）。兩者缺一不可。

MCP Tools 是什麼

"Tools are designed to be model-controlled, meaning that the language model can discover and invoke tools automatically."

（工具被設計為模型控制的，意即語言模型可以自動發現並調用工具。）

— MCP Specification: Tools

Agent Skill 是什麼

"Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations."

（技能按需載入，消除了在多次對話中重複提供相同指引的需要。）

— Anthropic: Agent Skills Overview

關鍵區別

維度MCP ToolAgent Skill
角色能力層（DO）— 廚房知識層（KNOW）— 食譜
控制者LLM 自動選擇關鍵字觸發 → 按需載入
粒度單一原子操作多步驟工作流編排
需要基礎設施是（Server process）否（純檔案）

Anthropic 官方：互補，不是取代

"We'll also explore how Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software."

（我們也將探討 Skill 如何補充 MCP 伺服器，透過教導 Agent 涉及外部工具的更複雜工作流程。）

— Anthropic Engineering Blog

"Skills describe the workflow. MCP provides the runner... Saying Skills killed MCP is like saying GitHub Actions killed Bash."

（Skill 描述工作流程。MCP 提供執行器……說 Skill 殺死了 MCP，就像說 GitHub Actions 殺死了 Bash。）

— Block/Goose Team

以本專案為例

🍳 MCP（廚房）

override_element_graphics 真的去改 Revit model 顏色，query_elements_with_filter 真的查 Revit 資料庫。

這些操作需要 WebSocket、Revit API、Transaction。Skill 做不了這些。

📖 Skill（食譜）

/fire-safety-check 告訴 AI「先查參數名 → 再列時效等級 → 再篩選 → 最後上色」。

這是知識和順序，不是能力。MCP 不管這些。

WHY
社群常爭論「Skill 殺死 MCP」——這是把抽象層級搞混的結果。MCP 解決「AI 怎麼動 Revit」（基礎能力），Skill 解決「AI 該照什麼順序動 Revit」（編排知識）。兩件根本不同層級的事，沒有取代關係。
HOW
本專案明確分層——MCP server 提供 239 個原子工具（純能力），Skill 編排工具呼叫順序（純知識）。一個 MCP 工具被多個 Skill 引用，一個 Skill 引用多個 MCP 工具——多對多關係，互不替代。
TECHNIQUE
Layered Capability Architecture · MCP as Runtime Bridge · Skill as Workflow Choreographer · M:N Tool-Skill Composition
為什麼這個區別很重要
把 Skill 當成「更聰明的 MCP」是業界最常見的誤解。
正確理解是：Skill 是「給 AI 看的 SOP 文件」，MCP 是「給 AI 用的螺絲起子」。
SOP 寫得再好也無法替代螺絲起子。
這也是為什麼 Block/Goose 那句「說 Skill 殺死 MCP 就像說 GitHub Actions 殺死 Bash」會在開發者圈廣傳——它一語道破「編排層」與「執行層」是不同抽象級別。BIM 場域更是如此：再強的 Skill workflow 也無法不通過 MCP 改變 Revit 一條牆。
深度閱讀 · MCP vs Skill 區辨
CORE ARCHITECTURE · 責任分工

Skill / Domain / Tool 的責任分工

三者各自管獨立職責：Skill 是流程、Domain 是方法、Tool 是操作。當 Domain 與 Skill 對方法描述不同時，以 Domain 為準（README.zh-TW.md「Domain、Skill、Tool 的分工」）。

上方區分流程、方法與工具；下方呈現 AI Client 到 Revit API 的連線
概念示意圖（AI 生成），非軟體畫面。上方：Skill 流程、Domain 方法、Tool 操作三種責任；下方：AI Client 經 MCP Server、Revit Add-in 到 Revit API 的連線。卡片邊框顏色只是區分三張卡，不是 Domain 五分類。
流程

Skill（流程・.claude/skills）

放在 .claude/skills/{name}/SKILL.md，是 AI 執行工作流程的編排層。關鍵字觸發後按需載入，告訴 AI「該做什麼步驟、引用哪個 Domain、呼叫哪些 MCP Tool」。

本專案目前 61 個 Skill。

方法

Domain（方法・domain/）

放在 domain/*.md。BIM SOP、法規邏輯、計算方法；人類與 AI 共用的知識層，不能全英文化。不可協商的限制——法規、SOP、計算公式、邊界案例，被多個 Skill 引用（複用）。

本專案目前 94 個 Domain。

操作

Tool（操作・MCP-Server/src/tools、MCP/Core/Commands）

MCP-Server/src/tools/*.ts 定義 MCP 工具與輸入 schema；MCP/Core/Commands/*.cs 是真正呼叫 Revit API 的實作。

本專案目前共 239 個 Tool。

MAINTENANCE · 維護規則不屬於這三種職責

CLAUDE.md 是專案的 AI 指引檔，記載專案維護規則（建置、部署、QA/QC、記錄）與多 AI Client 共用指引；AGENTS.md 與 GEMINI.md 刻意轉向它（CLAUDE.md 第 3 行）。GEMINI.md 是指向 CLAUDE.md 的薄殼。它不是第四種架構層，不放工作流程步驟或具體算法。

Domain 為什麼獨立於 Skill 存在

BIM 的知識是共用的——防火法規同時被消防檢查與元素上色引用。Domain 獨立於 Skill 存在，是因為知識不應該重複在每個 Skill 裡。

實例：防火 Domain 被兩個 Skill 引用

domain/fire-rating-check.md 同時被以下兩個 Skill 引用（.claude/skills/fire-safety-check/SKILL.md、.claude/skills/element-coloring/SKILL.md）：

如果防火法規條文更新，只動 domain/fire-rating-check.md 一處，兩個 Skill 引用的是同一份方法。這就是「Domain 是本體」（P5）的具體含義。

WHY
分工不是「為了好看」，是讓每一類內容各自好維護——知識不重複寫在每個 Skill 裡，Skill 調整步驟時不必改法規原文，Tool 的實作改動也不必重寫方法。
HOW
遵守單一職責：
• Skill = 何時觸發 + 工作流順序
• Domain = 法規 + 公式 + 邊界案例
• Tool = 單一原子操作（查詢或修改 Revit）
CLAUDE.md 另載維護規則與 Domain 觸發表（見上方「維護規則」）。避免混放——Domain 不寫工作流、Skill 不寫法規條文。
TECHNIQUE
Separation of Concerns · Single Source of Truth (CLAUDE.md) · Multi-Client Entry Pattern · M:N Skill-Domain Composition
為什麼要分工
很多 BIM 工具死於「所有邏輯擠在一個 plug-in 裡」——
升級規範要重編譯、換 AI 要重寫工具、改流程要動 C# code。
本專案把方法與流程放在 markdown，操作放在 Tool，各自獨立維護。
這也是為什麼「Skill / Domain 都用 markdown」是刻意設計——任何老師都能用記事本寫，不需要 IDE、不需要編譯、不需要 Git 進階知識。降低貢獻門檻 = 知識複利的起點。
深度閱讀 · 責任分工
COMMUNICATION · 技術通訊

技術通訊架構

Skill / Domain / Tool 是「責任分工」，下面這個是「技術四層」——AI Client → MCP Server → Revit Add-in → Revit API。

AI Client (Claude Desktop / Gemini CLI / VS Code Copilot / Claude Code)
  ↓ stdio
MCP Server (Node.js/TypeScript) — MCP-Server/src/index.ts
  ↓ WebSocket (ws://localhost:8964)
Revit Add-in (C#；R22–R24 為 .NET Framework 4.8，R25–R26 為 .NET 8) — MCP/Application.cs
  ↓ ExternalEventManager (UI thread)
CommandExecutor → Revit API

另有一個「embedded」方向——WPF chat window 內嵌在 Revit Add-in，直接呼叫 AI API，繞過 MCP Server。這是曾規劃的方向，非已實作功能（CLAUDE.md Project Overview：repo 內尚無實作）。Add-in 的 .NET 版本依 Revit 版本而不同（README.md 第 88 行）。

WHY
為什麼不直接 AI Client ↔ Revit API？因為Revit API 太底層——LLM 要傳 ElementId、Transaction、ViewSet 這些原生型別，每次都得編 boilerplate。MCP Server 中間層把這些封裝成 239 個語意化工具（check_smoke_exhaust_windows 比 FilteredElementCollector.OfCategory(...) 友善 100 倍）。
HOW
AI Client（stdio）→ MCP Server（Node.js TypeScript）→ WebSocket（port 8964）→ Revit Add-in（C#）→ Revit API。每層做協議翻譯 + UI 執行緒守門。port 8964 由 Add-in 啟動（HttpListener），MCP Server 連入。
TECHNIQUE
Four-Layer Communication Architecture · WebSocket Bridge · ExternalEvent UI-Thread Guard · stdio MCP Transport
為什麼選 WebSocket 不是 REST
REST API 適合「一問一答 + 無狀態」，但 Revit 操作是「連續對話 + 有 transaction state」。
WebSocket 保持連線、減少 handshake 開銷、UI thread 同步更穩。
port 8964 是 0425 開始就固定的——記得這個數字，因為「Port 被占用」是 3 個最常見的部署問題之一（其他兩個：DLL 沒部署、路徑寫錯）。詳見 故障排除。
MULTI-CLIENT · 不同入口同一目的地

多 AI Client 統一架構

本專案支援多個 AI Client，採用「不同入口、同一目的地」規範。

項目 Claude Code Gemini CLI VS Code Copilot
行為指引 CLAUDE.md GEMINI.md → CLAUDE.md .github/copilot-instructions.md
Skills .claude/skills/SKILL.md .gemini/skills/SKILL.md instructions 引導
Domain 文件 共用 domain/ 共用 domain/ 共用 domain/
MCP Tools 共用 239 個工具 共用 239 個工具 共用 239 個工具
Event Log 共用 log/ 共用 log/ 共用 log/

SKILL.md 格式遵循 Agent Skills 開放標準（YAML frontmatter + Markdown body），Claude Code 與 Gemini CLI 皆原生支援。

WHY
設計師不該被綁定特定 AI 廠商——今天用 Claude，明天可能要換 Gemini 或 Copilot。如果每個 AI 都要重寫一套 Skill / Domain，知識資產就死在工具升級時。「不同入口、同一目的地」確保你今天投入的 domain，明天還能用。
HOW
行為指引層用 symlink / 薄殼指向（GEMINI.md 內容就是 CLAUDE.md）。Skill 層遵守 Anthropic 制定的 Agent Skills 開放標準（YAML frontmatter + Markdown），任何支援標準的 AI Client 都能用。Domain / MCP / Log 全跨 client 共用。
TECHNIQUE
Multi-Client Convergence Pattern · Anthropic Agent Skills Standard Compliance · Symlink Pattern for Behavior Guidance · Shared Domain Knowledge Base
為什麼不綁定單一 AI
教設計師「只能用 Claude」，第二年 OpenAI 出新版設計師會跑光。
教設計師「用任何 AI 都能跑這套 SOP」，他們會帶著 SOP 跟你走 10 年。
知識的長壽 > 工具的時髦。
這也是為什麼採用 Anthropic Agent Skills 開放標準而不是自製格式——標準化會讓「貢獻你的 Skill」變成可移植資產，不是被某家公司鎖住的奴隸契約。Domain 用 Markdown 也是同理——人類可讀、AI 可讀、任何工具可讀。
深度閱讀 · 多 AI Client 策略
QUICK LINKS · 深入了解

下一步閱讀

📖 61 個 Skill 完整索引

每個 Skill 的觸發關鍵字、引用 Domain、呼叫工具一覽。

📚 94 Domain 完整索引

每個 Domain 的觸發詞、被引用 Skill、檔案位置。

🛠 Level 1 貢獻範本

停車場檢討範例——2 個檔案完成 Skill + Domain 貢獻，不需寫程式碼。

💡 P5 — Domain 是本體

為什麼 Domain 是 MCP 的核心資產（哲學層論述）。