構建高效 Skill 九大最佳實踐

Derek（Claude Code 核心工程師）在「慢學AI」講座中提出的 Skill 建構框架：三層九條，分別解決 Skill 的被看見、靈活複用、有狀態與可組合三個問題。

三層九條

📝 內容層：被看見與被理解

解決「Skill 存在但 AI 找不到 / 不知道什麼時候用」的問題。

1. Description 寫清觸發條件

description 欄位要說明「何時使用」，而非只列功能。這是 Skill 能否被 AI 發現的第一道門檻。

# ❌ 不好
description: "部署工具"
 
# ✅ 好
description: "在你準備好要把程式碼合併到 main 並部署到 staging/production 時使用"

2. 不陳述顯而易見的知識

聚焦補充 AI 不知道的：上下文、團隊偏好、踩坑經驗。

# ❌ 浪費空間
# Skill 用途：執行 git commit
 
# ✅ 有價值
# 注意：客戶不喜歡 Helvetica 字型和藍色 #0066FF，禁用

3. 建立 GOTCHAS（避坑指南）段落

記錄具體踩坑（如「不要在迴圈中呼叫 API，會慢 100 倍」）是 Skill 最有價值的內容，需持續更新。

🏗 結構層：可複用且不僵化

解決「Skill 太死板、上下文爆炸、無法維護」的問題。

4. 用檔案系統 + 漸進式揭露

把 Skill 組織為資料夾而非單檔，用 REFERENCES.md 或 assets/ 存詳細文件，讓 AI 按需載入：

.claude/commands/deploy/
├── SKILL.md              ← 精簡主指令（AI 一定讀）
├── common-mistakes.md    ← 按需讀入
├── preferences.md        ← 按需讀入
└── scripts/              ← 可執行工具

5. 仔細設計配置流程

需要用戶配置的資訊（如 Slack 頻道），用 config.json 持久化：

• 首次執行：詢問用戶
• 後續：自動讀取

讓 Skill 從「無狀態工具」升級為「有狀態助手」。

6. 避免過度約束

指令應約束「目標」而非「路徑」：

# ❌ 太死板（寫死執行順序）
# 先跑 lint → 再跑 test → 再跑 build → 再部署
 
# ✅ 給 AI 靈活性
# 部署前確保：測試通過、規範符合、構建成功

⚡ 高階技術層：有狀態與可組合

解決「Skill 缺記憶、重造輪子、規則無法動態啟停」的問題。

7. 實現記憶與資料儲存

對抗無狀態問題：執行後寫入日誌，下次讀取，只報告新變化。

# 每次執行後 append 到 skill-log.json
# 下次啟動時讀取，差分輸出「自上次以來的新事件」

8. 儲存指令碼並生成程式碼

將穩定能力封裝為可呼叫指令碼與輔助函式，讓 AI 負責「組合」而非「重造輪子」：

# scripts/check-tests.sh → AI 直接呼叫，不每次重寫

9. 使用按需 Hooks

對僅在特定場景需要的嚴格規則（如防危險命令），設計臨時啟用的 Hook，只在當前 session 有效，結束後自動失效。

# SKILL.md 中
在開始修改 production 資料庫前，請啟用 guardrails hook：
[安裝臨時 hook 的指令]

總覽

層次	問題	9 大實踐
內容層	被看見 + 被理解	① description ② 不陳述顯而易見 ③ GOTCHAS
結構層	可複用且不僵化	④ 檔案系統+漸進式揭露 ⑤ 配置流程 ⑥ 避免過度約束
高階技術層	有狀態 + 可組合	⑦ 記憶/資料儲存 ⑧ 指令碼封裝 ⑨ 按需 Hooks

相關概念

強連結（原文明確提及）

• SKILL.md 規範 — 本實踐的直接實作目標
• Skills 九種類型 — 九大實踐適用於所有九種類型
• Hooks — 實踐 ⑨（按需 Hooks）的底層機制
• Skills 生態運營策略 — 組織層面如何讓已建好的 Skill 持續進化

推斷連結（LLM 認為相關，待確認）

• 反饋循環 ?? — GOTCHAS 段落的更新本身就是一條反饋循環
• claude-reflect ?? — 自動把反饋寫入 CLAUDE.md / Skill 的工具，與實踐 ⑦ 理念一致

← 回到 wiki