skill-lens

skill-lens 是一款针对 Agent Skill（SKILL.md）的评测工具，让「这次改动到底有没有让技能变好」变成一个可量化、可报告、可接入 CI 的分数与退出码。Agent Skill 本质上是一段提示词，而提示词会随改动悄悄退化；skill-lens 让用户在技能旁编写评测用例，运行用例、为结果打分，并给出整轮运行的唯一结论。技能与用例都只是该工具的输入，工具本身不内置任何被测技能，因此任意技能仓库都能低门槛采用。

核心能力

• 输出断言：对智能体的输出做子串、正则与精确匹配断言。
• 行为断言：检查智能体调用了哪些模拟工具、调用顺序，以及哪些工具绝不能被触碰——例如未经查询就批准的退款，仅靠输出断言无法发现。
• 成本约束：为每个用例设置 token、费用与延迟上限。
• 表达质量评分：基于评分细则的 LLM 评审为每条细则给出一个结论及对应证据，专治「解释得是否清晰」这类无法用子串判断的要求。
• 触发可观测：mode: offered 把技能注册为工具而非强制加载，使「是否触发技能」成为可观测的选择，从而用负样本控制住「什么都触发的技能总是满分」的问题。
• 增量对比：每个用例运行两次，一次带技能、一次对基线（无技能或从 git 取上一版本），并基于差值设门禁。
• 离线免费运行：默认运行器可完全离线、无需 API Key 地跑通用例。
• 多框架支持：安装 skill-lens[pydantic-ai] 使用 Pydantic AI 运行器，skill-lens[langchain] 则使用 LangChain 运行器。
• CI 友好：输出可被流水线读取的分数、报告与退出码，直接用作出入门禁。

安装配置

1. 准备 Python 3.11.4 或更高版本。
2. 安装工具并附带 Pydantic AI 运行器：uv tool install "skill-lens[pydantic-ai]"，或使用 pip install "skill-lens[pydantic-ai]"。
3. 如需 LangChain 运行器，安装 skill-lens[langchain]；只要离线默认运行器时可去掉扩展。
4. 克隆示例仓库以获取自带用例：git clone https://github.com/EmadMokhtar/skill-evaluator.git 并进入目录，或直接指向自有存放 SKILL.md 的目录。
5. 若要在本工具仓库内开发，先运行 uv sync 准备开发环境，并在命令前加 uv run。

使用步骤

1. 准备技能与用例：任意包含 SKILL.md 的目录即为一个技能，其评测用例放在同目录下（如 csv-report.eval.yaml）。
2. 运行评测：用 skill-lens 对技能目录执行评测，产出分数与逐用例报告。
3. 检查行为与成本：查看模拟工具调用顺序、禁用工具是否被触碰，以及 token、费用、延迟是否超限。
4. 接入 LLM 评审：为需要主观判断的细则启用基于评分细则的评审，获取逐条结论与证据。
5. 开启增量门禁：为每个用例运行带技能与基线两次，基于差值设定门槛，防止改动引入退化。
6. 接入 CI/CD：在流水线中调用 skill-lens，依据退出码决定构建是否通过。

适用场景

• 在 CI/CD 中为 Agent Skill 建立回归测试与质量门禁。
• 团队协作中判断某次对 SKILL.md 的改动是否真正提升了效果。
• 验证技能是否在恰当的时机触发，避免「什么都触发」的伪高分。
• 对智能体的工具调用行为做安全审查，确保危险操作不被误触发。
• 控制智能体的 token、费用与延迟成本。
• 用 LLM 评审为难以量化的表达质量提供可追溯评分。

适用人群

• 维护 Agent Skill / SKILL.md 的开发者。
• 需要为 AI 智能体建立评测体系的团队。
• 负责 CI/CD 与质量门禁的工程人员。
• 研究提示词与智能体行为评测的研究者。
• 使用 Claude Code、Codex 等支持技能机制的 AI 编程用户。

工作原理

skill-lens 把技能目录与其旁挂的评测用例作为输入，用 Pydantic AI 或 LangChain 运行器驱动智能体执行用例，再对结果进行多维度评估：输出用子串、正则与精确匹配断言；行为通过模拟工具检查调用序列与禁用工具；成本核对 token、费用与延迟上限；表达质量由基于评分细则的 LLM 评审逐条判定并附证据。它还能以 offered 模式把技能注册为工具，使触发与否成为可观测指标，并通过带技能与基线的双次运行计算差值，最终汇总为整轮运行的一个结论与退出码，供流水线门禁使用。

官方链接

• PyPI：https://pypi.org/project/skill-lens/
• 文档：https://emadmokhtar.github.io/skill-evaluator/
• GitHub：https://github.com/EmadMokhtar/skill-evaluator