Skill Optimizer

Skill Optimizer v1.0.0

> 優化 SKILL.md 的 token 使用效率，同時保持功能完整

快速開始

# 分析單一 skill
/skill-optimizer analyze [skill-path]

# 優化單一 skill
/skill-optimizer optimize [skill-path]

# 批次分析整個 repo
/skill-optimizer audit [repo-path]

---

1. 優化原則

1.1 Token 效率金字塔

               ┌─────────┐
               │ 必要的  │ ← 保留：triggers, 核心知識
               ├─────────┤
               │ 有用的  │ ← 精簡：最佳實踐, 常見錯誤
               ├─────────┤
               │ 美化的  │ ← 移除：ASCII art, 裝飾性圖表
               ├─────────┤
               │ 範例化  │ ← 外連：模板, 完整範例, checklist
               └─────────┘

1.2 核心策略

| 策略 | 說明 | 節省估計 | |------|------|----------| | 分層載入 | 核心 + 擴展分離 | 40-60% | | 外連參考 | 大型範例移到獨立檔案 | 20-30% | | 精簡表達 | 移除冗餘修飾語 | 10-15% | | 圖表簡化 | ASCII → 簡潔描述 | 5-10% |

---

2. 分層結構

2.1 建議的 Skill 結構

skill-name/
├── SKILL.md           # 核心層 ( 20 行)
- 模板 (> 10 行)
- 詳細 checklist
- ASCII 圖表 (> 10 行)

---

## 3. 優化流程

### 3.1 分析階段

Step 1: 統計 ──────────────────────────────────────── wc -l SKILL.md # 總行數 grep -c "^#" SKILL.md # 章節數 grep -c "```" SKILL.md # 程式碼區塊數 grep -E "┌|└|│|─" SKILL.md | wc -l # ASCII 圖表行數

Step 2: 分類 ──────────────────────────────────────── 識別各區塊的類型： □ 核心知識 (必要) □ 最佳實踐 (有用) □ 範例/模板 (可外連) □ ASCII 圖表 (可簡化) □ 裝飾性內容 (可移除)

Step 3: 評分 ──────────────────────────────────────── Token 效率分數 = 核心內容行數 / 總行數 × 100

優秀: > 70% 良好: 50-70% 需優化: 70%

• [ ] 無 > 20 行的範例
• [ ] 無 > 10 行的 ASCII 圖表
• [ ] 有 extended/ 目錄放置擴展內容

4.2 內容檢查

• [ ] Frontmatter 完整 (triggers, keywords)
• [ ] 適用場景明確
• [ ] 核心概念精簡
• [ ] Sharp Edges 保留
• [ ] 大型範例已外連

4.3 連結檢查

• [ ] 外連路徑正確
• [ ] extended/ 檔案存在
• [ ] 參考資源可訪問

---

5. 範例：優化前後對比

Before: game-design (934 行)

章節分布：
├── 核心知識: 200 行 (21%)
├── 範例/模板: 450 行 (48%) ← 可外連
├── ASCII 圖表: 180 行 (19%) ← 可簡化
└── 最佳實踐: 104 行 (11%)

Token 效率: 21% (需優化)

After: game-design (280 行)

章節分布：
├── 核心知識: 180 行 (64%)
├── 簡化圖表: 30 行 (11%)
├── 最佳實踐: 50 行 (18%)
└── 外連指引: 20 行 (7%)

Token 效率: 64% (良好)
節省: 70% tokens

---

6. 自動化腳本

6.1 分析腳本

#!/bin/bash
# skill-analyzer.sh

SKILL_PATH="$1"

echo "=== Skill Analysis ==="
echo "Total lines: $(wc -l /dev/null || echo 0)
  EFF=$((100 - ASCII * 100 / LINES))

  if [ $LINES -gt 500 ]; then
    STATUS="⚠️"
  elif [ $LINES -gt 300 ]; then
    STATUS="🟡"
  else
    STATUS="✅"
  fi

  printf "%-40s %8d %9d%% %s\n" "$NAME" "$LINES" "$EFF" "$STATUS"
done

echo ""
echo "Legend: ✅ Good (500)"

---

7. 常見問題

Q: 分層後如何確保完整功能？

A: 核心層包含 80% 常用功能。當需要完整範例時，AI 會自動提示：

「需要完整的 GDD 模板嗎？我可以載入 extended/templates.md」

Q: 外連檔案會增加複雜度？

A: 是的，但：

• 大多數情況不需要載入
• 按需載入節省 token
• 結構更清晰

Q: 如何判斷內容是否該外連？

A: 使用「3 次法則」：

• 如果這段內容在 3 次對話中只用到 1 次 → 外連
• 如果每次都用到 → 保留在核心

---

版本歷史

| 版本 | 日期 | 變更 | |------|------|------| | 1.0.0 | 2026-01-15 | 初版：Skill 優化方法論 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: miles990
• Source: miles990/claude-domain-skills
• License: MIT

Install and usage instructions live in the source repository linked above.