Claude Skills 設計原則與工作流對應
核心概念
Skill 的定義：Skill 是把重複能力封裝成可被 Claude 在正確情境下取用的工作單元。它不只是一段 prompt，而是一組完整的執行規格，可以包含：
- Instructions（必要）：觸發條件、執行步驟、輸出格式
- Scripts（可選）：自動化腳本（bash、Python）
- Templates（可選）：輸出骨架或格式範例
- Examples（可選）：少樣本示範，幫助 Claude 校準輸出品質
Skill 的核心價值是：把「需要每次重新解釋」的知識移出對話，讓 AI 在適當時機自動取用，減少用戶認知負擔。
林彥廷的「公司組織圖」框架把 Claude Skills 生態系分為五大部門 48 人，核心比喻是：每個 skill 是一位有明確職責與觸發時機的員工。找 skill 就是招募對應職能的人，組合 skill 就是設計組織分工。這個視角與設計原則互補：設計原則回答「如何寫好一個 skill」，生態系視角回答「現成有哪些 skill、各負責什麼、如何組合應用」。
設計原則
好的 Skill 必須能回答以下五個問題：
| 設計維度 | 說明 | 壞例子 | 好例子 |
|---|---|---|---|
| 觸發條件 | 什麼情境下才啟動這個 skill？ | 「當你需要幫助時」 | 「用戶說本次工作即將結束 / session 結束 / 做個摘要」 |
| 輸入 | 需要哪些前置資訊才能執行？ | 不說明 | 「需要本次對話內容 + 當天日期 + 上次交接文件路徑」 |
| 輸出 | 完成後產出什麼？格式為何？ | 「一份摘要」 | 「YAML frontmatter + 五段固定格式 Markdown 文件，存為 交接-YYYY-MM-DD-sessionN.md」 |
| 邊界 | 這個 skill 不碰什麼？止於何處？ | 不說明 | 「只輸出摘要文件，不主動修改任何 wiki 或 raw 筆記」 |
| 失敗模式 | 什麼情況下會跑偏？如何預防？ | 不說明 | 「若對話太短（< 3 個實質操作），提示用戶確認是否真要輸出交接」 |
Description 是搜尋索引，不是說明書
Description 越豐富，Skill 越不容易被正確執行。 Claude Code 用 Description 做語義搜尋，決定「這個 skill 是否與目前任務相關」。若 Description 包含執行細節，Claude 可能跳過 Body——造成 skill「被看見但沒被正確跑完」的隱性錯誤。
正確設計：Description 只放觸發條件，執行細節全部在 Body。
| ❌ Description 過豐富 | ✅ Description = 觸發條件 |
|---|---|
| 「當用戶說要結束 session 時，產出交接文件，格式含 frontmatter + 五段 Markdown……」 | 「當用戶說本次工作即將結束 / session 結束 / 做個摘要 / 這次要結束了時觸發」 |
口訣：Description 讓 skill 被找到；Body 讓 skill 被正確跑完。
撰寫細節：Instructions、Examples、觸發條件
來源：Anthropic 官方 PDF「The Complete Guide to Building Skills for Claude」
Instructions 長度：建議 500 字以內，超過時觸發精準度下降。過長的原因通常是把「背景知識」塞進 instructions；正確做法：背景知識移到 templates/，instructions 只留執行流程。
Examples 數量：1–3 個足夠，超過 5 個可能讓 Claude 過度依賴格式、失去靈活性。每個 example 應提供「完整情境 + 完整輸出」，不是片段摘要。
觸發條件設計：觸發詞應「窄而精」，列出 3–5 個正例語句，可選加 1–2 個反例。
強制執行設計：Iron Law 與 Gate Function
在 Skills 裡加入「不可繞過的強制步驟」，比增加更多指令更有效：
Iron Law：在 skill body 的第一行宣告前提條件——「在做 X 之前，必須先確認 Y 已完成。沒有 Y 就不繼續。」
Gate Function（結構化語法版本）：
BEFORE [主要動作]
→ 先決條件清單（必須全部通過）
ONLY THEN [主要動作]反合理化表（Rationalization Table）：預先列出「可能的繞過理由 + 反駁」，讓模型在執行前就看到自己的合理化路徑。
三層載入機制（Progressive Disclosure）
Skills 的核心效率原則：不把所有內容常駐在 context，而是依需求分三層載入：
| 層次 | 內容 | 常駐狀態 | Token 成本 |
|---|---|---|---|
| Metadata（第 1 層） | skill 名稱 + 觸發條件描述 | 永遠存在 | ~35 tokens |
| Body（第 2 層） | 完整執行指令、格式規格、邊界說明 | 觸發後載入 | 幾百至幾千 tokens |
| Resources（第 3 層） | 模板、範例、外部文件 | 執行時才讀取 | 按需，不佔用常態 context |
若有 20 個 Skills，全部常駐需要 10,000 tokens/session；三層載入只需 700 tokens 常駐，被觸發的 skill 才付出 Body 的 token 成本。
和 99 Templates/ 的分工
- Template（
99 Templates/）：定義格式骨架。是靜態的「填空表格」，人類或 AI 都可以直接使用。 - Skill（Claude skill 系統）：定義執行流程。是動態的「觸發→執行→收尾」流程，知道什麼時候觸發、呼叫哪個 template、最後把共用資源更新完。
舉例：延伸方向.md 是 template；vault-session-handoff skill 是執行規範，定義觸發詞、掃描對話的步驟、呼叫模板的方式、存檔路徑與命名規則。
生態系：五大部門架構
01 翻譯部（2 人）
- baoyu-translate：四段式翻譯流程（分析→翻譯→校正→潤色），支援自訂詞彙表
- taiwan-traditional-chinese：460+ 筆台灣 vs 對岸術語對照稽核
02 內容創作部（21 人）
代表 6 位：baoyu-url-to-markdown / baoyu-youtube-transcript / baoyu-infographic / baoyu-xhs-images / baoyu-format-markdown / baoyu-post-to-x/wechat/weibo
03 設計部（8 人）
- frontend-design（Anthropic 官方）：強調「選一個 BOLD 美學方向再寫程式」
- ui-ux-pro-max：50+ 風格、161 配色、57 字體配對
- ckm-design 系列（6 人）：brand / design-system / ui-styling / slides / banner-design
04 工程部（14 人）
obra/superpowers 整套。核心 5 個：brainstorming / writing-plans / test-driven-development / systematic-debugging / verification-before-completion（「宣稱完成前必須跑驗證指令」）
05 行政部（5 人）
- find-skills：
npx skills find搜尋全球 skill 生態系 - skill-creator（Anthropic 官方）：含 eval 評測、效能基準、自動優化 description 觸發精準度
- gstack-workflow-assistant：AI 工作流團隊（CEO 審查、工程規劃、code review、shipping、QA）
Skills 與 Plugin Marketplace 的關係
官方 Skills repo（anthropics/skills）：官方維護的 Agent Skills，包含 document skills（docx、pdf、pptx、xlsx）、知識管理 skill 等。
Claude Code Plugin Marketplace：Skills 可以打包進 Plugin 對外散布。Plugin 是「多個 Skills + MCP + Commands 的打包層」，詳見 延伸方向。單一 Skill 是能力單元，Plugin 是可部署的能力組合。
Claude.ai / Claude Code / API 三端通用：同一套 Skill 設計原則適用於 Claude.ai 聊天介面、Claude Code CLI、以及 Claude API 自建 agent。
先實作一次，再沉澱成 Skill
「先跑通一次流程、調整滿意後再沉澱成 Skill」——這個順序在 Vault 的實際工作流中反覆被驗證。先實作再封裝的好處：規則穩定後才封裝、用戶能驗收、邊界清楚（什麼情況不適用的反例自然浮現）。
對應的 Skill 化原則：Skill 是把「已知能做到的事」外置化，不是讓 AI 去摸索「能不能做到」。
claude-skill-code-cleanup：用 Skill 維護 Skill 的 meta loop 案例
（GitHub Hao0321/claude-skill-code-cleanup，42 stars／8 forks，MIT，最後 push 2026-06-15；2026-06-26 api.github.com 直讀，原記 19★/06-02 已過時）
掃描 延伸方向.md / prompt / markdown codebase 中的語義問題，先報告問題清單 → 等使用者確認 → 才執行修改。設計亮點：「先報告再執行」的邊界設計，和 FLUX Vault 的「不主動靜默修改」原則完全吻合；Skill 本身負責掃描 Skill 目錄，形成維護自身品質的 meta loop。
8 維度兩模式（2026-06-26 深扒補強，可當瘦身 checklist 直接借用）：Mode A 程式碼清理＝① 語意重複（同概念不同字也算，linter 看不到）② 命名不一致 ③ 可抽 reusable 模組（重複≥3 次+邏輯獨立）④ 過長檔案（>800 行／函數>100 行警告）；Mode B repo 稽核＝⑤ 私公版 sync GAP ⑥ release 一致性（tag/release/CHANGELOG/README）⑦ cross-link 完整性 ⑧ 版本標記漂移。其「語意重複偵測＋只報告不改檔」與 規則檔 S05「提案→複查→執行」同構——Cowork 跑不了 Claude Code skill，故借方法不裝工具：把這 8 維度納入既有規則檔瘦身流程的掃描項（2026-06-26 已實跑掃過 規則檔/延伸方向，報告見 內部筆記）。詳見 延伸方向 code-cleanup 節。
我的觀點
建立：2026-05-25；合併整理：2026-06-05
先封裝高頻、規則穩定、可驗收的工作：Skill 化的前提不是「這件事可以自動化」，而是「這件事的規則已經穩定到可以明確描述」。
Skill 是「外置規則」，不是「外置思考」：好的 skill 封裝的是規則和流程，不是判斷力。判斷要留給 Claude 在執行時靈活應用。
Skill 組織圖的本質是 Harness 設計的具體化：林彥廷把 skill 比作「員工」，本質上是說每個 skill 是一個有明確觸發條件、有邊界的 agent——和 Harness Engineering 的「從期望行為反推 harness 元件」是同一件事。找 skill 就是找對應行為的 harness 元件。
superpowers 的 verification-before-completion 直接對應 FLUX Vault 的 Gate Function 規則：安裝這個 skill 後，Claude Code 會自動帶這個行為——不需要在每份 規則檔 裡重複寫這條規則。
「延伸方向 包越大越難維護，拆出來更好維護」——實務佐證 single-purpose 原則（2026-06-15，外部創作者）：本頁已從多角度主張「小而精」（Description 只放觸發、Instructions ≤500 字、single-purpose、skill-master 治理層）；外部創作者（MadebyPan，已在 來源追蹤表 追蹤表）作為實際大量產 skill 的創作者，給出「大包難維護、拆出來更好維護」的第一線確認——這不是新原則，而是把本頁的設計主張從「理論/官方建議」補上「實務者用維護成本背書」。與本庫 規則檔 rule-only 瘦身、延伸方向「精簡優於詳盡」同一條脈絡：壓的是單元的肥大與雜訊，拆分讓每個單元職責乾淨、context 不互搶。→ 延伸方向
「最值錢的是 gotchas，不是正向流程」——Skill 反常識設計（2026-06-17，FB 快刀青衣／歸藏萬字長文）：歸藏總結寫 skill 的反常識，三點對本庫直接增量： ① gotchas／負面規則 >> 正向流程：skill 最值錢的不是「怎麼做」的步驟，而是「別這麼做」的偏見清單（踩過的坑、反例）。對照本庫 延伸方向「踩坑紀錄家族」與 規則檔 禁止事項——我們早在做，歸藏給了它明確原則：負面邊界比正向規則更難複製、也更值錢；下次設計 Vault skill 把「不要做什麼」獨立成段，別只寫 happy path。 ② 一鍵生成 Skill 只能當初稿：本頁「先實作再沉澱成 Skill」的反向佐證——AI 生成的 skill 沒踩坑過，缺的正是 gotchas。 ③ AI 是放大器非平權器：同一 skill，會用的放大產能、不會用的放大混亂；普通人卡在「交互心智」非技術門檻。對課程的意涵：教 skill 機制不夠，要教交互心智（怎麼判斷、怎麼下邊界），正是「真的學會」的差異點。
「先找活，再配 Skill」——工位先於工具（2026-07-10，回到 Axton）：Axton 以單月 55,000+ 訊息的用量實測，自寫 70+ skill 最後每天真正在用的只有 6 個；他的結論是多數人順序反了——不是裝 skill 找用途，而是先把工作流拆成工位，每個工位才配對應 skill（他的 6 工位＝選題監控/三 AI 互審/封面配圖/圖解動畫/字幕校對＋一稿變文章/一鍵發布）。這把本頁「找 skill＝找對應行為的 harness 元件」再往上游推一步：期望行為之前，先有工位定義。對本庫的含義：① 70→6 的淘汰率佐證「意圖停泊型孤島」是常態而非例外，入庫閘門與雷達觸發條件的保守設計是對的；② 評估任何新 skill 前先問「它落在我哪個工位」（入庫／發文／配音／驗收），沒有對應工位就不裝——與「rubric 內嵌取代親裝」（2026-06-28 立場）同一脈絡。→ 延伸方向 Axton 節 2026-07-10 增量
（2026-06-05 決策更新）整合方向確認為 A（規則文件化，skill 為輔）：選擇在 Codex 任務交接模板中顯性寫入驗收清單步驟，而不是只依賴 superpowers skill 的隱性行為。核心理由：Cowork 看不到 skill 內部行為，但能看到 Codex 任務模板和 規則檔 規則；跨工具協作場景下，行為透明性優先於安裝便利性。
課程框架：B 主線 + A 進階的兩層設計
| 層次 | 內容 | 受眾 |
|---|---|---|
| 主線（B）：痛點語言 | 「你的知識庫是一堆孤島還是一張網？」視覺對比說明連結稀疏 vs 密集的差距 | 所有學員 |
| 進階（A）：設計原理 | 「分類管流程，連結管意義」——資料夾結構管處理流程，概念層管跨域語義連結 | 想深入理解系統設計的學員 |
對 FLUX Vault 的優先排序：Facebook 入庫和 wiki audit 是目前最適合 skill 化的兩個工作——高頻、規則文件已存在（SOP 在 延伸方向.md）、輸出有明確格式。