Claude Skill 怎樣才算頂尖？拆解 23 個 skill 後我找到 7 個設計原則

起因：拉了一個 repo，想知道裡面的 skill 到底好不好

公司有一個 awesome-mcp-and-skills repo，收了 23 個 Claude Skill。我想知道：這些 skill 的品質到底如何？有沒有明確的教學教我怎麼自己部署新 skill？

Claude 的分析：有料，但沒有手把手教學

Claude 花了三輪深讀，把 23 個 skill 的完整原始碼都看過一遍後告訴我：

格式統一，每個 skill 都有 SKILL.md，用 YAML frontmatter 定義 name、description
範例豐富，從簡單（單檔腳本）到複雜（DAG 多階段 + sub-skills）都有
但沒有「從零建一個 skill」的 step-by-step 教學——你得靠讀現有範例反推結構

我的提問：哪些 skill 結構平庸、哪些頂尖？我想掌握原理原則

既然沒有教學，那我就從實例學。我請 Claude 做多層推理，對 23 個 skill 做品質分層。

Claude 的回答：S / A / B 三級分層

S 級（頂尖，直接當範本抄）

Skill	為什麼頂尖
pdf-master	唯一有 DAG 架構 + manifest.yaml + sub-skills。index.json 專門為 AI Agent 設計（preview / needs_ocr 旗標）。並行 OCR、retry + fallback
Anthropic 官方四件套（docx / pdf / pptx / xlsx）	共用 office/ 基礎設施、XSD schema 驗證、反模式文件（“NEVER 用 unicode 上標”）、強制 QA 迴圈
moenv-news-daily-report	382 行操作手冊級 SKILL.md。有執行預算（tool call 上限）、反模式警告、自檢協議
gpt-image-2-generate-image	三層觸發設計（精確→口語→需求推論）。模式決策樹、allowed-tools、安全不變量

B 級（反面教材）

Skill	問題
bdd	最差：六句命令式中文無結構、硬寫專案名 “botrun-horse”、觸發詞過度寬泛
plotly-html-report	description 宣稱支援 heatmap / choropleth，但程式碼只實作 7 種圖表

我又追問：那到底什麼原則讓 S 級是 S 級？

Claude 的回答：七大設計原則

原則 1：Description 是路由表，不是說明書

description 是 Claude 決定「要不要啟動這個 skill」的唯一依據。頂尖做法是三層觸發：

層 1 — 精確匹配：OpenAI、GPT、gpt-image-2
層 2 — 口語化：「那個會思考的生圖模型」
層 3 — 需求推論：精確多語系文字渲染、logo
+ 消歧義：與其他 skill 的區別

平庸做法是塞 12 個觸發詞成一段，含「需求分析」「最佳實踐」等過度寬泛的詞。

原則 2：SKILL.md 是給 Claude 的 Prompt，不是給人的文件

Anthropic 官方 skill 的寫法像是在寫 system prompt：用 CRITICAL、NEVER 標記硬約束，提供正確 vs 錯誤的對比範例。人類看的文件放 docs/，Claude 看的指令放 SKILL.md。

原則 3：宣告 allowed-tools 收斂權限

不宣告 = 預設全開。23 個 skill 只有 3 個做了這件事，但這是安全關鍵。

原則 4：用 `${CLAUDE_SKILL_DIR}` 不要硬寫路徑

硬寫路徑 = 別人 clone 到不同位置就壞了。

原則 5：輸出要同時服務人和 AI Agent

HTML 報告給人看，JSON 結構化結果給下一個 skill 接。pdf-master 的 index.json 就是最佳範例。

原則 6：大型用 DAG 分階段，小型保持單腳本

三個以上階段、有條件式執行時，用 manifest.yaml 宣告 DAG。

原則 7：加入自檢協議與執行預算

沒有預算 = Claude 可能無限迴圈呼叫工具。沒有自檢 = Claude 可能產出不完整就宣告完成。

我的提問：來實戰——挑一個 S 級 skill 部署看看效果

Claude 的回答：部署 pdf-master

選了 pdf-master（DAG 架構、sub-skills、AI Agent 索引），複製到 ~/.claude/skills/pdf-master/，用一份 11 頁的標書 PDF 實測：

[OK] 分頁完成：11 頁
     圖片：11 張
     文字：11 個 txt
     需 OCR：0 頁

產出的 index.json 每頁有 preview（前 200 字）和 needs_ocr 旗標，AI Agent 不用逐頁開檔就能決定下一步。這就是 S 級的設計深度。

我又追問：我自己的 md-to-pdf-kit 呢？能不能也升到 S 級？

我有一個自建的 Markdown 轉印刷級 PDF 工具，程式碼品質不錯（零框架、版本鎖定、中文排版），但完全沒有 skill 包裝。

Claude 的體檢結果：底層 A+，包裝 0 分

原則	改造前	改造後
Description 路由表	0/10（無 SKILL.md）	9/10
SKILL.md 是 Prompt	4/10	9/10
allowed-tools	0/10	10/10
`${CLAUDE_SKILL_DIR}`	0/10	10/10
輸出服務人和 AI	6/10	8/10
DAG 分階段	3/10	9/10
自檢 + 執行預算	7/10	9/10

改造做了什麼：

三支腳本加 --input / --output CLI 參數——向下相容，原始工作流不壞
建立 SKILL.md——三層觸發、DAG 流程圖、反模式（NEVER/CRITICAL）、自檢協議
建立 manifest.yaml——宣告 convert → export → verify 三階段 DAG

核心邏輯（MD parser、WeasyPrint CSS 注入、品質探針）完全沒動。改的只是「包裝」和「介面」。

測試結果

向下相容（原始 cd 2.Logic && node convert.mjs）：通過
Skill mode（--input / --output 從任意目錄）：通過
另開 Claude Code 視窗說「轉 PDF」：自動觸發 skill，通過

最後把 skill 也登錄回 awesome-mcp-and-skills repo，commit + push。

我學到的

Skill 的品質不在程式碼，在包裝——底層寫得再好，沒有 SKILL.md 就是 0 分。Description 是路由表、SKILL.md 是 prompt、manifest.yaml 是 DAG 宣告，三件套缺一不可。
七大原則是可操作的 checklist——不是抽象的「要寫好一點」，而是「description 要有三層觸發」「要宣告 allowed-tools」「要有自檢協議」，每一條都能直接對照打分。
從範本學比從文件學快——awesome-mcp-and-skills 沒有教學文件，但 S 級 skill 本身就是最好的教學。拆解 pdf-master 學到的比讀十份規格書多。