Skill Doctor —— Skill 體檢診斷工具
流程
- 讀取指定 Skill 目錄
- 檢查核心檔案是否存在（SKILL.md、gotchas.md 等）
- 呼叫腳本取得結構化報告：
python scripts/analyze_skill.py <skill_path> --output json，得到每個檢查項目的分數、問題與建議 - 針對每個低分項目（<70 分），在腳本報告基礎上補充具體優化建議 + 預期提升分數 + 工作量評估
- 列出所有可優化項目，讓使用者選擇接受哪些
- 對使用者接受的項目逐一優化（直接修改檔案）
- 優化完成後再次呼叫腳本重新體檢，輸出前後對比報告
Agent 負責智慧層（優化建議、使用者互動、執行修改），腳本負責穩定層（評分計算、結構化輸出）。腳本用法見 scripts/analyze_skill.py。
九大體檢項目
| 檢查項 | 檢查內容 | 通過標準 |
|---|---|---|
| description 檢查 | 是否寫成觸發條件，不是功能說明 | 包含觸發關鍵詞，長度<100 字元 |
| gotchas 檢查 | 是否有坑點記錄 | gotchas.md 存在且非空 |
| 檔案組織檢查 | 是否按三分類標準組織 | 根目錄僅 SKILL.md + gotchas.md + examples.md，參考資料在 reference/，腳本在 scripts/，設定在 config/ |
| 過度約束檢查 | 是否過度約束路徑 | 沒有「第一步第二步」等死板流程 |
| 已知知識檢查 | 是否重複 Agent 已知內容 | 沒有「什麼是 X」、「如何使用 Y」等教學 |
| 記憶體配置檢查 | 是否有 config.json | config.json 存在，有合理配置 |
| 腳本檢查 | 是否需要腳本但缺失 | 如需穩定能力，有 scripts 目錄 |
| hooks 檢查 | hooks 配置是否正確 | PreToolUse/PostToolUse 格式正確 |
| markdown 格式檢查 | 格式是否規範 | YAML、表格、程式碼區塊格式正確 |
體檢報告格式
{
"skill_name": "xxx",
"overall_score": 55,
"grade": "D",
"check_results": {
"description": {"score": 50, "issues": ["寫成功能說明"], "suggestions": ["改為觸發條件句式"], "expected_gain": 40},
"gotchas": {"score": 40, "issues": ["gotchas.md 是空殼"], "suggestions": ["補充 3 個以上真實坑點"], "expected_gain": 50}
},
"optimization_options": [
{"id": 1, "item": "description", "current_score": 50, "expected_score": 90, "gain": 40,
"effort": "低", "action": "重寫 description 為觸發條件句式",
"token_saved_per_call": 50, "time_saved_per_call_sec": 0},
{"id": 2, "item": "gotchas", "current_score": 40, "expected_score": 90, "gain": 50,
"effort": "中", "action": "補充真實坑點",
"token_saved_per_call": 0, "time_saved_per_call_sec": 180}
],
"overall_after_accept_all": 85,
"total_benefits": {
"token_saved_per_call": 200,
"time_saved_per_call_sec": 300
}
}
收益估算規則
| 優化類型 | Token 節省（每次呼叫） | 時間節省（每次呼叫） | 說明 |
|---|---|---|---|
| description 縮短 | 每條多餘字元×1 token | — | 減少 context 載入量 |
| gotchas 補充 | — | 每坑點 2-5 分鐘 | 避免重複踩坑除錯 |
| 檔案拆分 | (原行數-新行數)×3 tokens | — | 參考資料移入 reference/，按需載入不進 context |
| 過度約束→決策框架 | 每條死板步驟×20 tokens | 每步 10-30 秒 | 減少無效步驟執行 |
| 刪除已知知識 | 教材段落長度 tokens | — | 不重複 Agent 已知內容 |
| 腳本封裝 | — | 每次 1-3 分鐘 | 避免 Agent 每次重寫程式碼 |
收益為單次呼叫估算值，實際數值因 Skill 內容和使用方式而異。
關於「耗時」的說明：報告中的「耗時」指設計缺陷產生的額外浪費，而非技能執行總時長。具體包括：
- gotchas 缺失 → Agent 反覆踩坑除錯（每次 2-5 分鐘）
- 過度約束 → Agent 執行無意義的死板步驟（每步 10-30 秒）
- 腳本缺失 → Agent 每次重新編寫相同程式碼（每次 1-3 分鐘）
對比邏輯：優化前的數值 = 這些浪費的總和；優化後浪費歸零 → ~0；「節省」= 被消除的浪費量。優化後技能執行本身仍需要時間，但不再有這些額外損耗。
優化建議呈現
生成報告後，將可優化項以清單形式展示給使用者，每項包含：
### 🔧 可優化項
| # | 檢查項 | 當前分 | 預期分 | 提升 | 工作量 | Token/次 | 時間/次 | 操作 |
|---|-------|--------|--------|------|--------|---------|---------|------|
| 1 | description | 50 | 90 | +40 | 低 | ~50 | — | 重寫為觸發條件 |
| 2 | gotchas | 40 | 90 | +50 | 中 | — | ~3min | 補充真實坑點 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |
**接受全部優化後**：55分(D) → 85分(B)，提升30分
### 📈 綜合收益（單次呼叫）
- Token 節省：~200/次
- 時間節省：~5分鐘/次
- 踩坑規避：gotchas 補充後可避免常見錯誤
> **耗時統計口徑**：此處「時間節省」指**設計缺陷導致的額外浪費**，非技能執行總時長：
> - gotchas 缺失 → Agent 反覆踩坑除錯（每次 2-5 分鐘）
> - 過度約束 → Agent 執行無意義的死板步驟（每步 10-30 秒）
> - 腳本缺失 → Agent 每次重新編寫相同程式碼（每次 1-3 分鐘）
> - 優化前數值 = 浪費總和，優化後浪費歸零，「節省」= 被消除的浪費量
請選擇：
- **"全部接受"** — 一鍵優化所有項
- **"接受1,3"** — 只優化指定項
- **"跳過"** — 只看報告不做優化
使用者確認後執行
- 使用者選擇後，逐項修改對應檔案
- 每完成一項，標記狀態
- 全部完成後，重新執行體檢生成對比報告
前後對比報告格式
## 📊 優化前後對比
| 檢查項 | 優化前 | 優化後 | 變化 |
|-------|--------|--------|------|
| description | 50 (功能說明) | 90 (觸發條件) | +40 ⬆️ |
| gotchas | 40 (空殼) | 90 (充實) | +50 ⬆️ |
| ... | ... | ... | ... |
| **總分** | **55 (D)** | **85 (B)** | **+30 ⬆️** |
### 📈 綜合收益（單次呼叫）
| 維度 | 優化前 | 優化後 | 節省 |
|------|--------|--------|---------|
| Token | ~800/次 | ~600/次 | ~200/次 |
| 耗時浪費 | ~5min | ~0 | ~5min |
| 主檔案 | 466行 | 75行 | -84% |
> 耗時浪費 = 設計缺陷導致的額外開銷（踩坑除錯、冗餘步驟等），非技能執行總時長。見 [收益估算規則](#收益估算規則)。
### 已修改檔案
- `SKILL.md` — 重寫 description
- `gotchas.md` — 補充 5 個真實坑點
完整互動範例
見 examples.md 範例 9
評分等級
- A（90-100分）：優秀，遵循所有最佳實踐
- B（75-89分）：良好，有少量優化空間
- C（60-74分）：合格，有明顯改進點
- D（<60分）：不合格，需要重構
詳細檢查清單
常見坑點
優化範例
腳本
體檢核心邏輯封裝在 scripts/analyze_skill.py，Agent 透過呼叫它取得結構化評分：
python scripts/analyze_skill.py <skill_path> --output json # 步驟3：取得評分報告
python scripts/analyze_skill.py <skill_path> --output markdown # 可選：生成人類可讀報告
腳本負責：評分計算、問題檢測、等級判定（穩定層） Agent 負責：優化建議生成、使用者互動、檔案修改執行（智慧層）