Skill Tester

高级脚本测试

• 语法验证: 编译 Python 脚本以在执行前检测语法错误。
• 导入分析: 强制执行“仅限标准库”政策，识别外部依赖项。
• 运行测试: 使用示例数据执行脚本，验证 argparse 实现，测试 --help 功能。
• 输出格式合规性: 验证双重输出支持 (JSON + 人类可读文本) 以及正确的错误处理。

多维度质量评分

• 文档质量 (25%): SKILL.md 的深度和完整性、README 的清晰度、参考文档的质量。
• 代码质量 (25%): 脚本复杂性、错误处理稳健性、输出格式一致性、可维护性。
• 完整性 (25%): 必需目录的存在、示例数据的充足性、预期输出的验证。
• 可用性 (25%): 示例的清晰度、argparse 帮助文本质量、安装简便性、用户体验。

等级分类系统

根据复杂性和功能自动对技能进行分类：

BASIC 等级要求

• SKILL.md 至少 100 行
• 至少 1 个 Python 脚本 (100-300 行代码)
• 基础 argparse 实现
• 简单的输入/输出处理
• 基本文档覆盖

STANDARD 等级要求

• SKILL.md 至少 200 行
• 1-2 个 Python 脚本 (每个 300-500 行代码)
• 带有子命令的高级 argparse
• JSON + 文本输出格式
• 详尽的示例和参考资料
• 错误处理和边缘情况管理

POWERFUL 等级要求

• SKILL.md 至少 300 行
• 2-3 个 Python 脚本 (每个 500-800 行代码)
• 具有多种模式的复杂 argparse
• 复杂的输出格式化和验证
• 广泛的文档和参考材料
• 高级的错误处理和恢复机制
• CI/CD 集成能力

架构与设计

模块化设计哲学

skill-tester 遵循模块化架构，每个组件服务于特定的验证目的：

• skill_validator.py: 核心结构和文档验证引擎。
• script_tester.py: 运行时测试和执行验证框架。
• quality_scorer.py: 多维度质量评估和评分系统。

标准强制执行

所有验证均依据 references/ 目录中记录的明确标准进行：

• 技能结构规范: 定义强制性和可选组件。
• 等级要求矩阵: 每个技能等级的详细要求。
• 质量评分细则: 综合评分方法和权重。

集成能力

旨在无缝集成到现有的开发工作流中：

• Pre-commit 钩子: 防止不达标的技能被提交。
• CI/CD 流水线: PR 工作流中的自动化质量门禁。
• 手动验证: 用于开发期间验证的交互式命令行工具。
• 批量处理: 对现有技能仓库进行批量验证和评分。

实现细节

skill_validator.py 核心函数

# 主要验证工作流
validate_skill_structure() -> ValidationReport
check_skill_md_compliance() -> DocumentationReport  
validate_python_scripts() -> ScriptReport
generate_compliance_score() -> float

关键验证检查包括：

• SKILL.md frontmatter 解析和验证
• 必需章节的存在性 (Description, Features, Usage 等)
• 每个等级的最小行数强制执行
• Python 脚本 argparse 实现验证
• 标准库导入强制执行
• 目录结构合规性
• README.md 质量评估

script_tester.py 测试框架

# 核心测试函数
syntax_validation() -> SyntaxReport
import_validation() -> ImportReport
runtime_testing() -> RuntimeReport
output_format_validation() -> OutputReport

测试能力涵盖：

• 基于 Python AST 的语法验证
• 导入语句分析和外部依赖检测
• 带有超时保护的受控脚本执行
• Argparse --help 功能验证
• 示例数据处理和输出验证
• 预期输出对比和差异报告

quality_scorer.py 评分系统

# 多维度评分
score_documentation() -> float  # 权重 25%
score_code_quality() -> float   # 权重 25%
score_completeness() -> float   # 权重 25%
score_usability() -> float      # 权重 25%
calculate_overall_grade() -> str # A-F 等级

评分维度包括：

• 文档: 完整性、清晰度、示例、参考质量。
• 代码质量: 复杂性、可维护性、错误处理、输出一致性。
• 完整性: 必需文件、示例数据、预期输出、测试覆盖率。
• 可用性: 帮助文本质量、示例清晰度、安装简便性。

使用场景

开发工作流集成

# Pre-commit 钩子验证
python3 skill_validator.py path/to/skill --tier POWERFUL --json

# 全面的技能测试
python3 script_tester.py path/to/skill --timeout 30 --sample-data

# 质量评估和评分
python3 quality_scorer.py path/to/skill --detailed --recommendations

CI/CD 流水线集成

# GitHub Actions 工作流示例
- name: "validate-skill-quality"
  run: |
    python skill_validator.py engineering/${{ matrix.skill }} --json | tee validation.json
    python script_tester.py engineering/${{ matrix.skill }} | tee testing.json
    python quality_scorer.py engineering/${{ matrix.skill }} --json | tee scoring.json

批量仓库分析

# 验证仓库中的所有技能
find engineering/ -type d -maxdepth 1 | xargs -I {} python3 skill_validator.py {}

# 生成仓库质量报告
python3 quality_scorer.py engineering/ --batch --output-format json > repo_quality.json

输出格式与报告

双重输出支持

所有工具均提供人类可读和机器可解析的输出：

人类可读格式

=== SKILL VALIDATION REPORT ===
Skill: engineering/example-skill
Tier: STANDARD
Overall Score: 85/100 (B)

Structure Validation: ✓ PASS
├─ SKILL.md: ✓ EXISTS (247 lines)
├─ README.md: ✓ EXISTS  
├─ scripts/: ✓ EXISTS (2 files)
└─ references/: ⚠ MISSING (recommended)

Documentation Quality: 22/25 (88%)
Code Quality: 20/25 (80%)
Completeness: 18/25 (72%)
Usability: 21/25 (84%)

Recommendations:
• Add references/ directory with documentation
• Improve error handling in main.py
• Include more comprehensive examples

JSON 格式

{
  "skill_path": "engineering/example-skill",
  "timestamp": "2026-02-16T16:41:00Z",
  "validation_results": {
    "structure_compliance": {
      "score": 0.95,
      "checks": {
        "skill_md_exists": true,
        "readme_exists": true,
        "scripts_directory": true,
        "references_directory": false
      }
    },
    "overall_score": 85,
    "letter_grade": "B",
    "tier_recommendation": "STANDARD",
    "improvement_suggestions": [
      "Add references/ directory",
      "Improve error handling",
      "Include comprehensive examples"
    ]
  }
}

质量保证标准

代码质量要求

• 仅限标准库: 不得有外部依赖项 (pip 包)。
• 错误处理: 全面的异常处理，并带有有意义的错误消息。
• 输出一致性: 标准化的 JSON 模式和人类可读的格式化。
• 性能: 具有合理执行时间的验证算法。
• 可维护性: 清晰的代码结构、详尽的 docstrings，并在适当处使用类型提示。

测试标准

• 自测试: skill-tester 验证自身 (元验证)。
• 示例数据覆盖: 涵盖边缘情况和错误条件的综合测试用例。
• 预期输出验证: 所有示例运行产生可验证、可重复的输出。
• 超时保护: 对可能存在问题的脚本进行带超时限制的安全执行。

文档标准

• 全面覆盖: 所有函数、类和模块均有文档说明。
• 使用示例: 针对所有用例提供清晰、实用的示例。
• 集成指南: 逐步的 CI/CD 和工作流集成说明。
• 参考资料: 针对标准和要求的完整规范文档。

集成示例

Pre-Commit 钩子设置

#!/bin/bash
# .git/hooks/pre-commit
echo "Running skill validation..."
python3 engineering/skill-tester/scripts/skill_validator.py engineering/new-skill --tier STANDARD
if [ $? -ne 0 ]; then
    echo "Skill validation failed. Commit blocked."
    exit 1
fi
echo "Validation passed. Proceeding with commit."

GitHub Actions 工作流