91 個組件的 Skill 為什麼生不出一個訂單頁面？

🌏 Read this article in English

---

前陣子,團隊裡發生了一件事。

有個 Senior 工程師,花了兩週時間設計了一個「超級 Skill」。

裡面塞了 91 個 UI 組件、18 個頁面範本。

他自己也覺得這份工很扎實。

但當他試著用這個 Skill 生成一個全新的訂單管理系統時…

卡住了。

不是技術。

是邏輯。

Skill 知道怎麼畫按鈕。 但沒有取得 API 或資料來源的上下文。

Skill 知道怎麼排版表格。 但不知道表格資料來自哪個資料庫。

但問題是:他還說不出,這個 Skill 的能力邊界在哪裡。

---

Skill 的本質:是知識庫,不是自動化引擎

先說清楚。

Skill 不是確定性應用 runtime。

它是可載入的指令與資源。

Claude Code 先讀取 SKILL.md 的 frontmatter 與 description 進入 context。

需要時,才透過工具執行 scripts。

它並沒有「執行」你的應用程式邏輯。

它是在「閱讀」。

讀懂 constraint。

找到 template。

然後,重新組合。

SKILL.md (指令) + templates (範本) + tools (script)
                ↓
    Claude 讀取後「遵循指令」生成內容
                ↓
        不是自動化程式,是「知識庫」

它讀懂了 SKILL.md 裡的約束條件。

它找到了 templates 裡的結構。

然後,它根據這些資訊,重新組合出新的內容。

Skill 不是自動化引擎,它是知識庫。

這聽起來很抽象?

舉個具體的例子。

假設你有一個 Skill,專門用來生成 React 組件。

這個 Skill 裡有一個 Button.tsx 的範本。

當 Claude 使用這個 Skill 時,它會:

1. 讀取 Button.tsx 的結構。
2. 讀取 SKILL.md 中關於樣式、Accessibility 的規範。
3. 根據你的需求,填入新的文字、顏色、Icon。

它不會「執行」 Button.tsx。

它不會「運行」你的程式碼。

它只是「複製、貼上、修改」的進階版。

這就是為什麼單一通用 Skill 很難穩定生成可接入既有專案的完整功能。

因為專案不是「知識」。

專案是「上下文」。

Skill 是 IKEA 的家具包。

專案是那間 30 年的老房子。

你拿著 IKEA 的說明書,修不好老房子的水管。

---

5 個 Level 模型:Skill 的能力邊界

為了更清楚地理解 Skill 的邊界,我將它的能力分為 5 個 Level。

這 5 個 Level,不是技術難度的遞增,而是「資訊依賴度」的遞增。

Level	能力	風險	需要的上下文	驗證方式
1	參考資料	低	設計規範、UI 約束	視覺比對
2	範本填充	低	Schema、欄位來源	結構比對
3	多檔案生成	中	跨檔案依賴、驗證規則	單元測試
4	專案整合	高	專案結構、路由、狀態	端到端測試
5	全自動建構	高	業務邏輯、API 規格	staging E2E、合約測試、灰度發布與監控

Level 1:參考資料(穩定)

這是 Skill 最擅長的事。

有人問過我:「為什麼 Skill 生成的按鈕總是對的?」

因為你提供了一個 design-system.md,裡面寫著:

• 主色調:#007AFF
• 字體:Inter
• 圓角:8px

Claude 可以穩定地遵循這些規範,在任何生成的代碼中應用它們。

為什麼穩定?

因為這些資訊是「通用」的。

它不依賴於任何特定的專案。

它只依賴於「設計規範」本身。

Level 2:範本填充(可行)

你提供一個 page-template.md,裡面寫著:

• Header 區域
• Sidebar 區域
• Main Content 區域

你提供一個 schema.json,定義了資料結構。

Claude 可以生成一個基本的頁面骨架。

為什麼可行?

因為結構是固定的。

資料結構是定義好的。

Claude 只需要「填空」。

就像填色遊戲一樣。

Level 3:多檔案生成(有限)

這裡開始出現限制。

你希望 Skill 生成 UserList.tsx、UserDetail.tsx、UserForm.tsx。

Claude 可以生成這些檔案。

但限制是:

• UserList 需要知道 User 的資料結構。
• UserDetail 需要知道如何呼叫 API。
• UserForm 需要知道驗證規則。

上次 review 時我看到,Skill 生出來的 UserForm 把所有驗證規則寫死成 if-else。

因為 Skill 不知道你們用 zod。

這些資訊不在 Skill 裡。

Skill 只有「範本」。

沒有「上下文」。

所以,Claude 生成的代碼,往往需要大量的手動調整。

Level 3 的瓶頸不在於 Claude 的能力,而在於 Skill 缺乏『專案專屬資訊』。

Level 4:專案整合(困難)

直到你要生第一個真實頁面。

你希望 Skill 能自動生成整個專案。

包括:

• 路由設定
• API 呼叫
• 狀態管理
• 資料庫連線

為什麼困難?

因為每個專案的結構都不同。

• Next.js 用 app/ 目錄。
• Create React App 用 src/ 目錄。
• Angular 用 modules/ 目錄。

Skill 無法預知你的專案結構。

除非…

你把這些資訊寫進 Skill 裡。

但這樣做,Skill 就會變得越來越複雜。

越來越難以維護。

這時可以先把實驗範圍縮小:挑一個小功能試,定好回滾方式,兩週後拿數據說話。

「我想在這個小功能上試試看。如果出問題,我負責。兩週後我給你數據。」

這句話讓主管知道:你不是要偷懶,你是用更聰明的方式工作。

Level 5:全自動建構(不適合)

這超出了單一通用 Skill 的承擔範圍。

全自動建構需要:

• 業務邏輯的理解
• API 規格的掌握
• 狀態設計的判斷
• 資料庫 schema 的定義

這些都不是「知識」。

這些是「決策」。

Claude 可以幫你「執行」決策。

但它無法幫你「做出」決策。

因為決策需要上下文。

而 Skill 沒有上下文。

---

Level 4+ 邊際效益遞減的根本原因:資訊不在 Skill 裡

讓我們深入探討 Level 4 的挑戰。

假設你有一個 Skill,名叫 uiux-design-pro。

它包含了 91 個組件、18 個範本。

你希望用它生成一個「訂單清單頁面」。

Skill 可以生成 UI。

但缺的是:

• 專案結構在哪? (pages/ vs app/ vs views/)
• 路由怎麼配? (Next.js App Router? Angular Router?)
• API 在哪? (REST? GraphQL? 什麼格式?)
• 狀態管理? (Zustand? Redux? NgRx? Signals?)
• 認證機制? (JWT? Session? 需要權限檢查嗎?)
• 現有 components 有哪些可以重用?

這些資訊不在 Skill 裡。

這些資訊在『專案本身』。

Skill 是一個「通用」的知識庫。

專案是一個「專屬」的上下文。

通用 Skill 拿不到這些上下文,自然接不上。

除非…

你把專屬資訊變成通用知識。

但這是不可能的。

因為每個專案的專屬資訊都是不同的。

---

單一大型 Skill vs 分層 Skill:常見取捨

常見的做法是把更多責任放進 Skill,讓它越來越複雜。

uiux-design-pro
├── 91 組件 ✓
├── 18 範本 ✓
├── Page Generator ← 加這個?
├── API Generator ← 再加這個?
└── 最後變成維護成本升高的複合 Skill

這是一個邊際效益遞減的區域。

因為 Skill 的複雜度,會隨著專案數量的增加而擴大維護面。

較穩健的方向,是把通用知識與專案上下文分層管理。

Layer 1: 設計知識庫 (通用 Skill)
         ↓ 提供組件規格、設計約束
Layer 2: 專案專屬 Skill
         ↓ project-generator, schemas
Layer 3: Agent 協調器 (Task tool)
         ↓ 讀取專案結構 → 參考 Layer 1 → 生成代碼

Layer 1:設計知識庫(通用 Skill)

這是 uiux-design-pro。

它只包含:

• UI 組件規格
• 設計約束
• 樣式指南

它不包含任何專案特定的邏輯。

為什麼要這樣做?

因為設計規範是「穩定」的。

專案結構是「變化」的。

將兩者分離,可以保持 Skill 的穩定性。

Layer 2:專案專屬 Skill

這是每個專案獨有的 Skill。

它包含:

• 專案結構資訊
• API 規格
• 狀態管理方案
• 資料庫 schema

為什麼要這樣做?

因為這些資訊是「專屬」的。

它們只存在於這個專案中。

將它們放在專屬 Skill 中,可以確保資訊的準確性。

Layer 3:Agent 協調器

這是 Claude Code 本身。

它扮演「協調者」的角色。

它的工作流程是:

1. 讀取專案專屬 Skill(Layer 2)。
2. 參考設計知識庫(Layer 1)。
3. 生成代碼。

Agent 不是『執行者』,而是『整合者』。

它整合了「通用知識」和「專屬上下文」。

---

建議實作方式:兩種架構選擇

根據你的需求,可以選擇兩種實作方式。

方案 A:專案專屬 Skill

.claude/skills/
├── uiux-design-pro/          ← 保持不變,純設計知識
└── project-generator/        ← 新增,專案專屬
    ├── SKILL.md
    ├── templates/
    ├── schemas/
    └── generators/

優點:

• 資訊準確。
• 維護簡單。
• 可擴展性高。

缺點:

• 需要為每個專案創建 Skill。

方案 B:Schema-Driven

定義 page-schema.yaml,Claude 讀取後生成完整頁面。

優點:

• 結構化。
• 易於驗證。

缺點:

• 需要維護 Schema。
• 靈活性較低。

取捨討論:

• 如果你的專案結構變化頻繁,選擇 方案 A。
• 如果你的專案結構相對穩定,選擇 方案 B。

沒有最好的架構,只有最適合當前專案的架構。

---

市場訊號:Skill 設計的未來

以目前官方文件與實務案例看,Skill 機制還在演進…但有一件事是現在就能確定的:

Skill 的價值,取決於能否把上下文與判斷準則外顯化。

Skill 不會取代工程師的判斷力。

它只會放大工程師的判斷力。

工具是放大器。放大的是你本來就有的能力。

如果你沒有清晰的架構思維,Skill 只會讓你更快放大未校準的假設。

如果你有清晰的架構思維,Skill 會讓你更快落地已驗證的架構判斷。

Skill 教 Claude 怎麼做事。Context 才教 Claude 該不該做這件事。

---

下一步:想讓它知道更多,還是判斷更準?

比起先做超級 Skill,更值得先釐清三個上下文判斷點。

• 我的專案結構是什麼?
• 我的 API 規格是什麼?
• 我的狀態管理方案是什麼?

這些資訊,才是你真正需要的「知識庫」。

你今天的十分鐘,花在讓 Skill 多懂一點,還是讓上下文更清楚一點?