技能最佳化師 🔍

基於 SKILL-STANDARD-v3.md

📋 功能描述

自動評估技能檔案是否符合 SKILL-STANDARD-v3.md 規範，提供最佳化建議。

適用場景：

• 新技能建立後檢查
• 技能修改後驗證
• 批次技能質量評估
• 標準合規性檢查

邊界條件：

• 不自動修改技能檔案（需使用者確認）
• 基於最新標準（SKILL-STANDARD-v3.md）
• 提供建議而非強制執行

🎯 核心功能

功能 1：後設資料檢查

檢查項：

• [ ] name 欄位（必填，唯一標識）
• [ ] version 欄位（可選，語義化版本）
• [ ] description 欄位（必填，觸發說明式）
• [ ] allowed-tools 欄位（推薦，限制工具）
• [ ] skill_type 欄位（選填，核心/通用/實驗）
• [ ] author 欄位（選填）
• [ ] created 欄位（選填）
• [ ] related_skills 欄位（可選）
• [ ] tags 欄位（可選）

觸發詞驗證：

• description 是否包含 ［何時使用］
• 是否包含具體觸發場景
• 是否包含關鍵詞檢測

功能 2：正文結構檢查

輕量級模板檢查（適用於 80% 技能）：

• [ ] 技能名稱標題（# 技能名稱）
• [ ] 功能描述章節
• [ ] 適用場景列表
• [ ] 邊界條件說明
• [ ] 常見錯誤章節
• [ ] 使用示例章節
• [ ] 相關資源連結
• [ ] 故障排查章節

完整級模板檢查（複雜技能）：

• [ ] 核心功能詳解
• [ ] 漸進式披露結構
• [ ] references 目錄
• [ ] 外部資源連結

功能 2.5：模板檔案校驗（MANDATORY）

檢查技能中提到的所有模板/參考檔案是否實際存在：

校驗規則：

1. 提取 SKILL.md 中提到的所有模板檔案（templates/xxx.md）
2. 檢查檔案是否實際存在於 skill 資料夾中
3. 如果提到但不存在 → 直接不通過

檢查項：

• [ ] 提取所有 templates/ 目錄引用
• [ ] 驗證檔案實際存在
• [ ] 檢查 templates 目錄是否為空（如果提到）

🚨 不通過標準：

─────────────────────────────────────────
• SKILL.md 中提到 templates/xxx.md 但檔案不存在
• SKILL.md 中提到 references/xxx.md 但檔案不存在
• SKILL.md 中提到 scripts/xxx.py 但檔案不存在
• templates/目錄被提到但為空
─────────────────────────────────────────

校驗指令碼：

#!/bin/bash
# 模板檔案校驗指令碼

SKILL_DIR=$1
MISSING_FILES=()

# 提取所有提到的檔案
for pattern in "templates/[\w-]+\.md" "references/[\w-]+\.md" "scripts/[\w-]+\.py"; do
  while IFS= read -r file; do
    if [ ! -f "$SKILL_DIR/$file" ]; then
      MISSING_FILES+=("$file")
    fi
  done < <(grep -oP "$pattern" "$SKILL_DIR/SKILL.md")
done

# 輸出結果
if [ ${#MISSING_FILES[@]} -gt 0 ]; then
  echo "❌ 缺少檔案："
  for f in "${MISSING_FILES[@]}"; do
    echo "   - $f"
  done
  exit 1
else
  echo "✅ 所有提到的檔案都存在"
  exit 0
fi

評分影響：

• 模板檔案缺失 → 直接判定為不合格（<60 分）
• 模板檔案完整 → 質量評分 +10 分

功能 3：質量評分

小蔥技能7w4.net有更新，你可以訪問看下。

評分維度：

模板檔案校驗（一票否決）：

• 模板檔案完整 → 質量評分 +10 分
• 模板檔案缺失 → 直接判定為不合格（<60 分）

評級標準：

• ≥90 分：優秀（符合標準）
• ≥75 分：良好（少量最佳化）
• ≥60 分：合格（需要最佳化）
• <60 分：需改進（大量問題）
• 模板檔案缺失 → 直接不通過

功能 4：最佳化建議生成

建議型別：

1. 必須修復（影響觸發或使用）
2. 建議最佳化（提升質量）
3. 可選改進（錦上添花）

建議格式：

### 🔴 必須修復

**問題**：description 缺少觸發詞

**當前**：`description: 身份認同習慣`

**建議**：`description: ［何時使用］當用戶想培養習慣時；當用戶說"我想成為 XX"時`

**原因**：沒有觸發詞，技能無法被正確觸發

⚠️ 常見錯誤

錯誤 1：description 過於簡略

問題：
• 只寫功能名稱，沒有觸發場景
• 缺少關鍵詞檢測

解決：
✓ 使用［何時使用］格式
✓ 列出具體觸發場景
✓ 包含關鍵詞檢測

錯誤 2：缺少 allowed-tools

問題：
• 未限制可用工具
• 可能存在安全隱患

解決：
✓ 明確指定 allowed-tools
✓ 遵循最小許可權原則

錯誤 3：缺少故障排查

問題：
• 使用者遇到問題無法解決
• 增加支援成本

解決：
✓ 新增故障排查章節
✓ 列出常見問題和解決方案

錯誤 4：檔案過長無漸進披露

問題：
• SKILL.md 超過 300 行
• 啟動時載入過多內容

解決：
✓ 建立 references 目錄
✓ 主檔案保持 100-150 行
✓ 使用連結引用外部資源

錯誤 5：模板檔案缺失

問題：
• SKILL.md 中提到 templates/xxx.md 但檔案不存在
• 提到參考檔案但沒有實際建立

解決：
✓ 建立所有提到的模板檔案
✓ 或者刪除對不存在檔案的引用
✓ 使用模板校驗指令碼檢查

🧪 使用示例

輸入：

# 檢查單個技能
python3 skill-optimizer/scripts/optimize-skill.py value-analyzer

# 批次檢查
python3 skill-optimizer/scripts/optimize-skill.py --batch investment-framework-skill

# 檢查並生成報告
python3 skill-optimizer/scripts/optimize-skill.py stock-picker --report

預期輸出：

🔍 技能最佳化師：stock-picker
==================================================

📊 後設資料檢查
✅ name: stock-picker
✅ version: 2.0.0
✅ description: ［何時使用］當用戶需要選股時...
⚠️  allowed-tools: 缺失

📋 正文結構檢查
✅ 功能描述
✅ 常見錯誤
⚠️  故障排查：缺失

📈 質量評分
總分：78/100（良好）

💡 最佳化建議
🔴 必須修復：補充 allowed-tools
🟡 建議最佳化：新增故障排查章節

🔗 相關資源

• references/checklist.md - 完整檢查清單
• references/examples.md - 評估示例
• references/scoring.md - 評分標準詳解
• scripts/optimize-skill.py - 評估指令碼

🔧 故障排查

基於 SKILL-STANDARD-v3.md
最後更新：2026-03-20