skill-tester

技能测试器

验证技能包是否符合结构规范，测试 Python 脚本的语法和仅使用标准库的导入，并从四个维度（文档、代码质量、完整性、易用性）评定质量，给出等级和改进建议。支持 BASIC、STANDARD 和 POWERFUL 级别分类。

核心功能

• 结构验证 — 根据级别门槛检查必需文件、目录布局、YAML frontmatter 和必需的 SKILL.md 章节。
• 脚本测试 — 检查 AST 语法、仅使用标准库的导入，检测 argparse 和 __main__ 守卫，并运行时执行 --help 和示例数据。
• 质量评分 — 对四个同等权重的维度进行评分，得出总分、字母等级（A+ 至 F）和按优先级排序的改进路线图。
• 级别分类 — 按 BASIC / STANDARD / POWERFUL 要求评定 SKILL.md 深度、脚本数量/LOC、argparse、输出格式和错误处理。
• 双重输出 — 提供便于阅读的报告和用于 CI/CD 门禁的 --json 输出，并返回有意义的退出码。

适用场景

• 创建新技能并在发布前进行验证。
• 审核现有技能的结构、脚本和质量。
• 将质量门禁嵌入 CI/CD 流水线。

请先确认

验证前，请确认以下输入。如有任何内容未知或含糊，请提问——不要自行假设：

• 目标技能路径 — 要验证、测试和评分的技能目录（所有三个工具的处理对象）
• 目标级别 — BASIC / STANDARD / POWERFUL（--tier；用于设定必需章节、脚本数量和结构门槛）
• 通过门槛 — 最低质量分数 / 失败是否会拦截 CI（--minimum-score、退出码）

停止规则：只询问对结果影响最大的 2–3 项。如果用户表示“直接起草”，则继续操作，并在交付内容顶部列出假设。

快速开始

# Validate skill structure and documentation
python skill_validator.py engineering/my-skill --tier POWERFUL --json

# Test all Python scripts in a skill
python script_tester.py engineering/my-skill --timeout 30

# Score quality with improvement roadmap
python quality_scorer.py engineering/my-skill --detailed --minimum-score 75

工具

工具	用途	命令
skill_validator.py	根据级别规则验证结构、frontmatter、必需章节和脚本	python scripts/skill_validator.py engineering/my-skill --tier POWERFUL --json
script_tester.py	对脚本进行静态和运行时测试（语法、导入、argparse、--help、示例）	python scripts/script_tester.py engineering/my-skill --timeout 60 --json
quality_scorer.py	对四个质量维度评分，给出字母等级和改进路线图	python scripts/quality_scorer.py engineering/my-skill --detailed --minimum-score 75 --json

完整的参数表、输出格式和退出码，请参阅 references/tool-reference.md。

参考资料

根据任务加载相应的参考资料——保持此文件精简，按需获取详细信息：

• references/workflows-and-cicd.md — 三种核心验证工作流、级别要求表和质量评分表、CI/CD 集成、反模式、故障排除及成功标准。运行验证或配置 CI 门禁时阅读。
• references/tool-reference.md — 三个 Python 工具的完整参数表、输出格式和退出码。编写工具调用脚本或解读 JSON 输出时阅读。
• references/skill-structure-specification.md — 关于技能目录结构、必需文件和 frontmatter 的权威规范。定义“结构有效”的含义时阅读。
• references/tier-requirements-matrix.md — 完整的 BASIC/STANDARD/POWERFUL 要求矩阵，包含各级别的详细标准。评定或提升技能级别时阅读。
• references/quality-scoring-rubric.md — 详细的评分规则，列明各组成部分的权重和评分区间。解读或调整质量评分时阅读。

范围与限制

涵盖：

• 根据各层级（BASIC、STANDARD、POWERFUL）的要求，对技能目录进行结构验证
• 对 Python 脚本进行静态分析，包括语法检查、导入验证、argparse 检测和主程序保护验证
• 从文档、代码质量、完整性和易用性等多个维度进行质量评分
• 双重输出格式（供 CI/CD 流水线使用的 JSON，以及供开发者阅读的文本格式）

不涵盖：

• 脚本逻辑的功能正确性或算法准确性——测试器验证结构和规范，不验证业务逻辑
• 脚本的性能基准测试或内存分析——运行时分析请参见 engineering/performance-profiler
• 脚本代码的安全漏洞扫描——依赖项和代码安全审计请参见 engineering/skill-security-auditor
• 跨技能依赖项解析或集成测试——技能会单独验证，不检查技能间的兼容性

集成点

技能	集成方式	数据流
engineering/skill-security-auditor	验证通过后执行安全审计	skill_validator.py 确认结构符合要求后，skill-security-auditor 会扫描同一技能路径中的漏洞
engineering/ci-cd-pipeline-builder	将 skill-tester 嵌入为质量门禁阶段	流水线构建器会生成工作流 YAML，依次调用 skill_validator.py、script_tester.py 和 quality_scorer.py
engineering/changelog-generator	将质量评分变化纳入更新日志条目	比较不同版本之间 quality_scorer.py 的 JSON 输出，以呈现质量改进或退化
engineering/pr-review-expert	将验证报告附加到拉取请求审查中	skill_validator.py --json 的输出会作为 PR 评论发布，供审查者参考
engineering/performance-profiler	通过运行时分析补充结构测试	script_tester.py 确认执行成功后，performance-profiler 会测量执行时间和资源使用情况
engineering/tech-debt-tracker	随时间追踪质量评分趋势	定期采集 quality_scorer.py --json 的输出，以检测评分下降并标记技术债务