Skill Quality Checker

name: skill-assessment description: "Agent skill quality checker. Input a skill directory or skill files; output trigger clarity, metadata issues, examples, safety boundaries, installability, portability risks, and prioritized fixes. Review-only by default: does not publish, delete, rename, or archive without explicit approval." license: MIT

概述

skill-assessment 是一個輕量級靜態分析工具，用於評估 OpenClaw 技能的質量。它不執行任何程式碼，僅通過檔案分析和後設資料檢查，從文件完整性、程式碼規範性、配置友好度、維護活躍度四個維度對技能進行評分，幫助使用者快速篩選技能，為開發者提供改進方向。

觸發場景

• 當你想了解某個技能的可靠性和質量時
• 當你在多個相似技能間猶豫不決時
• 當你開發完技能，想檢查潛在問題和改進點時
• 當你需要批次評估所有本地技能，找出薄弱環節時

安裝

# 方法1：從 ClawHub 安裝（釋出後）
clawhub install skill-assessment

# 方法2：本地安裝（開發階段）
cd /path/to/skill-assessment
ln -sf $(pwd) ~/.openclaw/skills/skill-assessment

使用方式

基本用法

# 評估單個技能
skill-assess ~/.openclaw/skills/skill-creator

# 評估當前目錄下的技能
skill-assess .

# 批次評估所有本地技能
skill-assess --all

# 評估並生成JSON格式報告
skill-assess ~/.openclaw/skills/skill-creator --format json

# 僅顯示問題清單
skill-assess ~/.openclaw/skills/skill-creator --problems-only

# 對比兩個技能
skill-assess --compare skill-creator skill-audit
7w4.net提供免費和付費技能下載。

輸出示例

🔍 技能評估報告：skill-creator
📊 綜合評分：★★★★☆ (4.2/5)
⏱️ 評估用時：12秒
📁 技能路徑：~/.openclaw/skills/skill-creator

維度得分：
  文件完整性：★★★★☆ (4.0/5)
  程式碼規範性：★★★★★ (4.5/5)
  配置友好度：★★★☆☆ (3.5/5)
  維護活躍度：★★★★☆ (4.0/5)

⚠️ 發現問題：3個
✅ 通過檢查：21個
📋 詳細報告：~/.openclaw/skills/skill-assessment/reports/skill-creator_2026-03-12.md

評估維度

1. 文件完整性 (權重30%)

• SKILL.md 存在性：強制檢查，缺失則直接0分
• 必填章節：name, description, triggers, usage, installation, configuration
• 示例質量：示例是否可複製，是否有輸入輸出說明
• 配置說明：預設配置示例，環境變數支援

2. 程式碼規範性 (權重40%)

• 檔案結構：清晰的目錄組織（scripts/, templates/, examples/）
• 安全風險：硬編碼金鑰、危險許可權、注入漏洞
• 錯誤處理：set -e 或 try/catch，友好的錯誤提示
• 工具使用：許可權申請合理性，安全邊界

3. 配置友好度 (權重20%)

• 預設配置：合理的預設值，不暴露敏感資訊
• 配置方式：支援環境變數、配置檔案、命令列引數
• 錯誤提示：配置缺失時的明確提示和修復建議

4. 維護活躍度 (權重10%)

• 版本管理：語義化版本號（如 1.0.0）
• 更新記錄：CHANGELOG.md 或更新說明
• 最後更新：3個月內+2分，6個月內+1分，1年內+0.5分

評分演算法

總分 = 
  文件完整性得分 × 30% +
  程式碼規範性得分 × 40% + 
  配置友好度得分 × 20% +
  維護活躍度得分 × 10%

星級轉換： - 4.5-5.0: ★★★★★ (優秀) - 4.0-4.4: ★★★★☆ (良好)
- 3.5-3.9: ★★★☆☆ (中等) - 3.0-3.4: ★★☆☆☆ (一般) - 2.5-2.9: ★☆☆☆☆ (較差) - <2.5: ☆☆☆☆☆ (不推薦)

配置選項

在技能根目錄建立 config.yaml 或設定環境變數：

# config.yaml
weights:
  documentation: 0.3    # 文件完整性權重
  code_quality: 0.4     # 程式碼規範性權重
  config_friendly: 0.2  # 配置友好度權重
  maintenance: 0.1      # 維護活躍度權重

checks:
  enable_security_scan: true     # 啟用安全檢查
  enable_performance_check: false # 不啟用效能檢查（靜態分析不包含）
  min_score_to_warn: 3.0         # 低於此分數顯示警告

output:
  format: "markdown"    # 輸出格式：markdown, json, text
  save_report: true     # 儲存詳細報告
  report_dir: "./reports" # 報告儲存目錄

環境變數：

export SKILL_ASSESS_WEIGHTS='{"documentation":0.3,"code_quality":0.4}'
export SKILL_ASSESS_OUTPUT_FORMAT=json

檔案結構

skill-assessment/
├── SKILL.md                    # 本文件
├── assess.sh                   # 主評估指令碼
├── config.yaml                 # 預設配置
├── evaluators/                 # 評估模組
│   ├── doc_checker.sh          # 文件檢查
│   ├── code_analyzer.sh        # 程式碼分析
│   ├── config_validator.sh     # 配置驗證
│   └── maintenance_checker.sh  # 維護狀態檢查
├── templates/                  # 報告模板
│   ├── report.md.j2            # Markdown報告模板
│   └── summary.txt.j2          # 控制台摘要模板
├── examples/                   # 示例
│   ├── sample_report.md        # 示例報告
│   └── config.example.yaml     # 配置示例
└── reports/                    # 生成的報告儲存
    └── skill-creator_2026-03-12.md

故障排除

常見問題

1. 評估時間過長
2. 原因：技能檔案過多或包含大檔案

3. 解決：使用 --exclude 排除非必要檔案，或設定檔案大小限制

4. 誤報安全問題

5. 原因：檢查規則過於嚴格

6. 解決：調整 config.yaml 中的安全檢查敏感度，或新增例外規則

7. 缺少依賴工具

8. 原因：未安裝 jq、yq 等工具

9. 解決：brew install jq yq 或使用包管理器安裝

10. 許可權問題

11. 原因：無法讀取技能目錄
12. 解決：檢查目錄許可權，或使用 sudo（不推薦）

除錯模式

# 啟用詳細日誌
skill-assess ~/.openclaw/skills/skill-creator --verbose

# 檢視檢查過程
skill-assess ~/.openclaw/skills/skill-creator --debug

開發指南

新增新的檢查規則

1. 在 evaluators/ 目錄下建立新的檢查指令碼
2. 指令碼應輸出 JSON 格式的結果： json { "score": 4.5, "max_score": 5, "issues": ["問題描述1", "問題描述2"], "suggestions": ["改進建議1", "改進建議2"] }
3. 在 assess.sh 中註冊新的檢查器
4. 更新 config.yaml 中的權重配置

擴充套件評估維度

如需新增新的評估維度（如“效能表現”），需要： 1. 動態測試支援（選項2或3） 2. 在沙箱中執行技能測試用例 3. 測量執行時間和資源消耗

版本歷史

• v1.0.0 (2026-03-12): 初始版本，靜態分析四維度評估
• v1.1.0 (規劃中): 新增技能對比功能，整合到 ClawHub
• v1.2.0 (規劃中): 支援動態基礎測試（選項2）

相關技能

• skill-creator: 技能建立輔助工具
• skill-audit: 技能安全審計工具
• find-skills: 技能發現和搜尋工具

貢獻

歡迎提交 Issue 和 Pull Request： 1. Fork 本倉庫 2. 建立功能分支 3. 提交更改 4. 推送到分支 5. 建立 Pull Request

許可證

MIT License

這個技能質量評估工具整體表現良好，文件完善、配置靈活、安全檢查覆蓋全面。主要優點是結構清晰、使用簡單，能從文件、程式碼、配置、維護四個維度全面評估技能質量。不足之處是主指令碼的部分功能還未完全實現，生成的報告較為簡單。對於需要評估和篩選 OpenClaw 技能的開發者來說，這是一個值得一試的工具，但目前成熟度還有提升空間。