Skill Quality Checker

概述

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

输出示例

🔍 技能评估报告：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. 评估时间过长

   • 原因：技能文件过多或包含大文件
   • 解决：使用 --exclude 排除非必要文件，或设置文件大小限制

2. 误报安全问题

   • 原因：检查规则过于严格
   • 解决：调整 config.yaml 中的安全检查敏感度，或添加例外规则

3. 缺少依赖工具

   • 原因：未安装 jq、yq 等工具
   • 解决：brew install jq yq 或使用包管理器安装

4. 权限问题

   • 原因：无法读取技能目录
   • 解决：检查目录权限，或使用 sudo（不推荐）

调试模式

# 启用详细日志
skill-assess ~/.openclaw/skills/skill-creator --verbose

# 查看检查过程
skill-assess ~/.openclaw/skills/skill-creator --debug

开发指南

添加新的检查规则

1. 在 evaluators/ 目录下创建新的检查脚本
2. 脚本应输出 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