为 Agent 技能包加上静态检查

Skill 写好了，Agent 却不调用；引用的脚本不存在，运行时才报错；指令越补越长，每次激活都要付出上下文成本。这些问题很像配置文件里的错误，适合在执行前检查。

作者做的 Skill Inspector，就是给 SKILL.md 加上 lint、修复预览、测试生成和执行分析。它的核心主张很明确：Skill 应该像 API 契约一样接受工程检查。不过，能查出格式错误，与能证明 Agent 行为可靠，是两件需要分开看的事。

为什么 Skill 需要自己的 ESLint

一个 Skill 包通常包含 frontmatter、正文指令，以及脚本和参考资料。frontmatter 是文件开头的元数据，用来声明名称、描述等信息。

作者列出的故障都很具体：description 只写功能、不写使用时机，Agent 可能不会激活；引用的 scripts/helper.py 不存在；正文达到 9,000 tokens，每次激活都要加载；名称含有规范禁止的连续双连字符。

Skill Inspector 面向 agentskills.io 格式，提供 Web 界面和 CLI。作者称其静态检查覆盖该规范的全部规则，包括名称格式与长度、必填字段、描述长度限制、正文体积警告，以及未知 frontmatter 字段。每项问题都有规则 ID，严重程度分为 FAIL 和 WARN。

Skill 的描述还承担着路由职责：它要让 Agent 判断什么时候该调用。

这也是普通 Markdown 格式检查无法覆盖的部分。文档排版正确，不代表触发条件写清楚了。

先检查依赖和成本，再考虑润色指令

传入 --base-dir 后，工具会解析 scripts/、references/ 和 assets/ 下被引用的文件，检查缺失、空文件和 ../ 路径穿越。

它还把上下文成本拆成三部分：技能目录中的元数据占用、激活时加载的正文，以及读取全部参考资料时的按需上下文峰值。最后一项更接近成本上界，不能直接当作每次执行的实际消耗。

下面两条命令分别检查单个文件和完整技能包，第二条还允许 Claude Code 专用字段：

skill-inspector validate path/to/SKILL.md
skill-inspector validate path/to/SKILL.md --base-dir path/to/skill --mode claude-code

关键是第二行的 --base-dir，文件依赖解析从这里开始。--mode claude-code 则支持 Claude Code 专用 frontmatter 和列表形式的 allowed-tools。

修复功能会展示统一差异（unified diff），对元数据和命名执行确定性修复；可选的 LLM 步骤才会重构正文指令：

skill-inspector fix path/to/SKILL.md --dry-run
skill-inspector fix path/to/SKILL.md --apply

先看第一行的预览，再决定是否执行第二行。格式修复的结果容易核对，指令改写则还需要检查是否改变了适用范围。

模型评分和生成测试，能证明多少

LLM-as-a-Judge 会给描述质量、指令清晰度、范围与边界、token 效率四个维度打分，每项为 0 到 100。它支持 OpenAI、Anthropic 和本地 Ollama 模型；选择本地模型可以不使用 API key。

这些分数适合辅助审阅。原文没有给出评分与实际任务成功率之间的对照数据，也没说明不同模型打分是否一致。

工具还能生成 10 到 16 个合成测试场景，覆盖正常流程、对抗输入、工具失败和范围边界，导出 Pytest、JSON 或 Markdown。CLI 用法是 skill-inspector generate-tests path/to/SKILL.md --format pytest --output tests/test_skill.py。

但原文没有展示生成测试如何驱动真实 Agent、如何判定任务完成，不能仅凭导出 Pytest 就认为端到端行为已经验证。

轨迹分析器则接收 Agent 执行轨迹，寻找重复读文件、搜索循环、错误反复和上下文膨胀。它更接近运行后的性能排查，输入轨迹的格式和接入方式，原文没说清。

我的判断

我认同先把 Skill 当作可检查的软件资产。相比人工翻阅 Markdown，规则检查更适合持续发现漏文件、命名违规等问题；相比单纯让模型审稿，带规则 ID 的结果也更方便复查。

但「像 ESLint」目前是产品定位。作者列出了功能，没有提供准确率、误报率、成本下降或任务成功率数据，工程收益仍需实测。项目采用 MIT 许可证，版本为 v0.0.8，原文也明确说还处于早期。

可以优先采用可复核的静态检查，把模型评分和合成测试当作审阅辅助。

想试 Web 界面，可以克隆仓库后运行 make install && make dev，打开 http://localhost:5173；原文也提供了 docker compose up -d 的启动方式。

能拿来做什么

• 维护团队 AI 编程 Skill 时，先检查 description 是否同时写清功能与触发条件，再用 validate 排查格式问题。
• Skill 引用脚本、规范或示例文件时，使用 --base-dir 做完整包检查，把依赖缺失提前暴露出来。
• 对正文较长的 Skill，先看正文与参考资料的 token 分布，再判断哪些内容适合按需读取。
• 将生成的边界场景用于人工审阅，并结合实际执行轨迹检查循环与重复读取；自动修复前先查看 --dry-run 的差异。