Skills Eval — Agent Skill 评估框架

一套用于评估和优化 AI Agent Skill 质量的框架，支持确定性检查、LLM-as-Judge、多轮对话模拟和迭代优化。

项目结构

skills-eval/
├── eval_framework/          # 评估框架核心代码
│   ├── checker.py           # 确定性检查器 + CHECK_REGISTRY
│   ├── models.py            # Pydantic 数据模型
│   ├── runner.py            # 评估运行器
│   ├── benchmark.py         # Benchmark 聚合
│   ├── llm_judge.py         # LLM-as-Judge
│   └── config.py            # 配置
├── evals/                   # 各 skill 的评测配置
│   ├── product-design-module/
│   │   ├── evals.json       # 测试场景 + 期望
│   │   └── checks.py        # 自定义检查函数
│   ├── web-creator/
│   └── web-design-summary/
├── doc/                     # 文档
│   ├── research.md          # 深度 Research 报告
│   ├── eval-framework-guide.md  # 框架使用说明
│   └── skill-eval-optimization-guide.md  # 评测优化指南
├── run_llm_eval_web.py      # Web skill LLM 评测脚本
├── run_llm_eval_v2_full.py  # Product-design LLM 评测脚本
└── README.md

核心概念

评估方法论

六阶段核心循环：定义成功标准 → 手动试跑 → 构建 prompt 集 → 搭评估框架 → 跑评估 → 人工审查 → 改 Skill → 重跑

四维成功标准：Outcome / Process / Style / Efficiency

确定性检查 vs LLM-as-Judge

确定性检查（优先）：正则匹配、关键词检查、结构验证
LLM-as-Judge（补充）：语义理解、风格评估

结构化期望语法

在 evals.json 中使用三种语法编写期望：

语法	说明	示例
`re:pattern`	正则匹配	`re:### 3\.\d`
`any:w1,w2,w3`	任一关键词匹配	`any:summary,摘要,网页设计摘要`
纯文本	精确关键词匹配	`DOCTYPE`

迭代优化循环

设定目标阈值 → 测试 → 记录 → 总结 → 分析 → 优化 → 重新测试 → 直至达标

快速开始

1. 安装依赖

pip install openai pydantic

2. 运行评测

# 评测 web-design-summary skill
python run_llm_eval_web.py --skill web-design-summary

# 评测 web-creator skill
python run_llm_eval_web.py --skill web-creator

# 评测所有 web skill
python run_llm_eval_web.py --skill all

3. 添加新 Skill 评测

在 evals/ 下创建目录，编写 evals.json 和 checks.py
在 run_llm_eval_web.py 中添加测试场景和用户模拟策略
运行评测，分析结果，迭代优化

详细步骤参见评测优化指南。

评测结果示例

product-design skill 迭代历程

迭代	版本	确定性检查通过率	JSON 验证	关键改进
1	v1 (1056行)	3.0%	N/A	基线
2	v2 (213行)	8.6%	N/A	输出纪律+格式模板化
3	v2-full	11.6%	1/3	补齐外层skill+data外部化
4	+ checker优化	~40%	1/3	evals.json重写+any/re语法
5	+ max_tokens修复	96.6%	3/3	max_tokens增大+JSON截断修复

web-design-summary / web-creator skill

Skill	场景	v1 通过率	v2 通过率	关键改善
web-design-summary	模糊需求	25%	100%	强制提问补全四轴
web-creator	缺少摘要	66.7%	100%	前置skill检查

文档

深度 Research 报告 — 评估方法论研究
框架使用说明 — 评估框架 API 和配置
评测优化指南 — 实战经验总结，含迭代案例和检查清单

License

MIT