写完第一个版本的Skill体检器之后，我拿它去扫了自己维护的30个Skill。结果不出所料，一批Skill得了0分，但和预期差距太大——有几个我明明天天在用的Skill，居然被“体检器”判了死刑。我一开始以为是这些Skill真的年久失修，但一个个扒下来才发现，8个“0分”全是假象，真正的锅在体检器自己身上。

这个事挺值得聊的。现在做AI Agent、搞自动化的工作流越来越多，Skill这个概念已经从“给模型加一段提示词”演变成了一个带结构、带依赖、甚至带动态调用逻辑的工程单元。但市面上的Skill质量参差不齐，又没有统一的检测标准，全靠个人感觉：“应该能用吧”。我把这个“感觉”变成代码之后，反而逼出了很多平时根本注意不到的问题。

这篇文章就从头讲一讲，体检器是怎么设计出来的、为什么会把好Skill误判成0分、以及这8个“假0分”是如何被一步步识别出来的。

1. Skill体检器的设计思路：把“感觉”变成可量化的检测

1.1 为什么需要一个Skill体检器

先说背景。我自己日常会维护一批Skill，包括给Codex用的代码生成类技能、给Agent平台用的数据抓取类技能、还有一些像“画流程图”“写小说剧情大纲”这类偏内容生产的技能。以前测试Skill的方式很简单，就是把Skill装进去，跑一个样例，看着输出不错就算通过。但Skill一多，这个方法就彻底失效了。

一是时间成本：30个Skill，每个跑两三个样例，一个下午基本就没了；二是覆盖度问题：你验证了正常路径，但没验证异常路径——网络超时怎么办？模型不按格式输出怎么办？输入的长文本把上下文给撑爆了怎么办？三是回归测试没法做：Skill更新了一版，你根本不知道会不会把以前能跑通的场景给搞挂。

所以体检器本质上不是“评价Skill好坏”的工具，而是“自动发现Skill有没有出问题”的工具。它做三件事：按定义好的测试用例去执行Skill、检查执行结果是否符合预期、把不符合预期的Skill按严重程度打分。

1.2 体检器的检测维度是怎么设计的

在动手写体检器之前，我先把“一个Skill应该长什么样”拆成了六个维度。这六个维度不是拍脑袋定的，而是来源于那些真正“装上去却用不了”的失败案例：

• 文件完整性：Skill不是必须是一个文件，它可以是一个目录，包含SKILL.md、脚本、参考文档等。目录缺文件、文件名大小写不对，都会导致Skill无法加载。
• 元信息可解析性：Skill的name、description、version这些字段能不能被正确解析出来。很多工具依赖description来决定什么时候调用Skill，写得太烂就等于没有。
• Schema结构与代码一致性：Skill声明的输入参数和实际脚本/提示词接受的参数是否对得上。参数名不一致是最常见的低级错误。
• 上下文适配性：Skill在Agent中以“指令片段”的方式被注入，如果它对上下文长度、变量名有硬性依赖，脱离特定Agent环境就容易失灵。
• 执行链路可运行性：涉及脚本类Skill时，依赖的库、环境变量、外部API接口是否可用，直接决定Skill是真的能跑还是纸面能跑。
• 输出质量抽检：跑完Skill拿到的结果，到底是不是“可用”的。这一步最难自动化，因为模型输出存在随机性，得设阈值、做模糊匹配。

1.3 评分机制：为什么0分会出现

体检器的输出不是简单的“过/不过”，而是给每个Skill打一个0到100的分数。这个分数的计算逻辑是加权平均：文件完整性占20%，元信息占15%，Schema一致性占15%，上下文适配占10%，执行链路占25%，输出质量占15%。

这个权重我调了好几版，最终把“执行链路”和“文件完整性”加了重，因为这两项一旦出问题就是硬伤，Skill根本跑不起来，属于“一票否决”级别。但问题就出在这个“一票否决”上——加权平均模型天然会掩盖单项崩溃。后来我加了一条规则：任何一个维度如果得分低于20%，无论总分多少，直接判定为0分，标记为“存在致命缺陷”。

这个规则本身没毛病，但它是8个“假0分”的元凶之一。因为“维度过低”不一定是Skill坏了，也可能是体检器自己的检测环境出了问题。

2. 8个“假0分”的典型画像：体检器是怎么冤枉人的

第一轮体检跑完，30个Skill里11个挂了0分。我把每个0分Skill拉出来做人工复核，发现其中8个是误判。这8个误判不是同一个原因，而是每种情况踩了一个坑。我把它们整理成了8个画像，这节详细拆解。

2.1 画像一：依赖缺失被误判成执行失败

有一个“数学建模Skill降AI味”的技能包，内部用了一个Python脚本调numpy和scipy去做统计校验。体检器跑它的时候，执行链路这一项的检查脚本是直接从宿主环境起一个新的Python解释器来跑的——问题来了，那个环境里压根没装numpy。

报错信息是ModuleNotFoundError: No module named 'numpy'，按规则，执行链路出现异常直接给0分。但真实场景下，这个Skill是装在一个跑过pip install -r requirements.txt的Agent环境里的，numpy、scipy都是预装好的。

根因：体检器的执行环境和Skill的生产环境不一致。

这个坑很典型。我一开始图省事，直接用体检器所在虚拟环境的解释器去测所有Skill，但Skill脚本的依赖声明在Skill目录里，不在体检器里。踩了这个坑之后，我才意识到体检器必须模拟目标运行环境，而不是拿自己的环境去套。

后续的改良方法——体检器在测试脚本类Skill时，先读取Skill目录下的requirements.txt，在临时虚拟环境里安装依赖再执行测试。虽然每次体检会多花几十秒，但至少测试环境是和生产环境对齐的。

2.2 画像二：超时阈值设置太死，把慢Skill判成死Skill

有一个“打斗动作提示词Skill”，功能是根据角色状态生成动作分镜提示词。这个Skill本身调的是外部的动作词库，需要先构建一个语义检索索引。正常使用时，这个Skill的表现是慢热——第一次调用要花40多秒做索引预热，后续调用就很快了。

体检器执行测试用例时给的超时阈值是15秒，结果这个Skill每次都超时，被判了执行失败。我复核的时候手动跑第一次也等了40多秒，但第二次只用了3秒。

根因：体检器的超时阈值没有区分“冷启动超时”和“单次请求超时”。

这个问题的本质是性能测试和功能测试混在一起了。功能测试关心的是“能不能跑通”，性能测试才关心“跑得多快”。把两者混在一个阈值里，慢但可用的Skill就会被误杀。

后来体检器改了策略：一个Skill跑同一个测试用例三次，第一次的超时阈值放宽到60秒，后续两次用正常阈值15秒；同时会记录每次的执行耗时，单独输出一份性能报告。这样的0分才是真正的“既跑不通又跑不快”。

2.3 画像三：测试样本集太旧，Skill更新后检测还在“测过去”

有一个“Codex绘图Skill”，原本的输入样例是一个固定的RGB颜色值加主题描述，后来迭代版本把RGB颜色值换成了HSL格式，测试样例没同步更新。体检器按旧的样例跑，输入格式不匹配，Skill直接返回了一个错误对象。

根因：测试样本集的更新滞后于Skill本身的版本迭代。

这是Skill维护里最容易忽略的一个环节。Skill作者改了一个参数类型，但很少有人会同步把测试用例也改掉，因为“测试用例”在大部分个人项目的维护里根本没有地位。但正是这一段“没有地位”的代码，决定了体检器能不能反映真实情况。

我现在给每个Skill定了一条规则：修改Skill的输入输出格式时，必须同步更新体检器里的对应测试用例的schema定义；如果更新后的输入输出与用例不一致，体检器会打一个“用例漂移”警告，而不是直接判0分。

2.4 画像四：环境变量缺失，Skill躺着中枪

有个“AI备课Skill”需要读一个环境变量LESSON_RESOURCE_DIR来定位课件模板目录。在正常部署的Agent环境里，这个变量在启动时就被写好了。但体检器跑这个Skill时，是通过子进程方式执行的，子进程没有继承宿主环境变量，导致skill内部去读路径时拿到了一个空值，直接抛了异常。

根因：体检器的子进程隔离机制导致环境变量丢失。

这个问题的隐蔽性很强。从体检器的角度看，“执行异常”是真实发生的，Shell日志里的报错也是真实的；但从Skill的角度看，它在生产环境里从来没有遇到过这个问题。如果不是我复核时随手打了echo $LESSON_RESOURCE_DIR，可能永远发现不了是环境变量的问题。

后来我改了体检器的执行机制——子进程启动前会把宿主环境变量全量透传，同时提供一个env_overrides配置项用于单独设置每个Skill需要的自定义环境变量。这个配置还能顺便解决“不同Skill需要不同API Key”的测试场景。

2.5 画像五：语义校验太严格，把合格输出当成乱码

这个是8个“假0分”里面最狡猾的一个。体检器有一个“输出质量抽检”维度，它会对Skill返回的结果做关键词匹配和格式校验。有个“写小说好用的Skill”跑出来的结果是合乎要求的，但因为模型输出的内容里有一段语气词“嗯、啊、这个嘛”，被语义校验的正则规则判定为“包含非正式表达”，输出质量得分直接被压到了15%，触发了“维度过低一票否决”规则。

根因：语义校验规则缺少对“风格化输出”的豁免机制。

写小说这种内容生成型Skill，它的“好”没有唯一答案。一段有大白话和语气词的文本，放在公文写作里是垃圾，放在网文对话里是正确的。体检器用一套通用的文本规范去套所有Skill的输出，必然会出现这种“过拟合的误判”。

这个问题的解法不是去掉语义校验，而是给每个Skill配一套独立的输出判定模板。小说类的Skill，我允许口语化表达，只看“是否包含小说结构要素”；代码类的Skill，我只看“能否被AST解析”。通用校验只做最粗粒度的检查——空输出、报错信息、超长输出。

2.6 画像六：并行执行冲突，测试时互相污染

体检器是并发跑测试用例的，一次体检同时跑5个Skill，每个Skill都会起独立的进程。本身没什么问题，但有一个Skill是“画流程图的Skill”，它执行时的临时文件名固定为/tmp/flow.png，另一个Skill执行时也用了同样的路径。两个进程同时写同一个文件，导致其中一个Skill读取到的图片文件是另一个Skill的产物，格式校验直接失败。

根因：并行测试时的临时文件资源竞争。

这个坑在串行测试时完全不存在，一旦并发就会出现偶发失败。更坑的是，它不是每次都失败，取决于两个进程谁先写完文件，所以排查起来很费劲——你单跑这个Skill是好的，跑体检就会随机挂掉一个。

体检器后来对所有测试用例执行时产生的临时文件和缓存目录做了强制隔离，每个用例跑在一个独立沙箱目录里，目录名带用例ID和随机数。这个方案在“测试环境不相互污染”这个问题上是最省心的。

2.7 画像七：输出解析逻辑过于死板，Skill被格式反噬

“画流程图的Skill”和“流程图的Skill”这两个，一个用Mermaid语法输出，一个用SVG标签输出。其中SVG的那个Skill，输出的是一个完整的HTML文档。体检器的输出校验只匹配了<svg>标签，没考虑SVG是包裹在HTML容器里的，结果判定“未检测到有效的SVG输出”，执行成功但输出无效，总分被降成0。

根因：校验规则里的“存在性断言”没有适配真实输出格式的层叠关系。

这个问题和画像五类似，但维度不同——画像五是“风格过于灵活”，这里是“结构过于灵活”。体检器校验输出合法性时，如果想用“检测有没有某个标签/字段”来判定，就必须先搞清楚Skill的真实输出结构。最好用JSON Schema或者XPath这类结构化的查询方式，而不是简单的字符串includes判断。

现在体检器的输出校验支持两种模式：严格模式（JSON Schema校验）和宽松模式（结构化包含校验），默认用宽松模式，只有明确的输出规范文档才开严格模式。

2.8 画像八：评分权重失衡，总分被单一维度拖垮

最后一个“假0分”是我在设计评分机制时自己埋的雷。上面说过，任何单项维度低于20%就会触发0分强制判定。有一个“WorkBuddy实用Skill合集”，文件完整性和元信息都满分，但执行链路维度因为测试环境的依赖问题被打到了18%。

单独看执行链路这一项的报错，确实有问题——某个依赖库没有预装。但从Skill在真实环境里的表现看，30次调用有29次是好的。问题在于那个依赖库是可选依赖，只在某个特定参数分支下才需要加载。体检器的一次性测试没有覆盖到那个分支，但“依赖加载失败”的报错被记录了下来，单个维度分被拉低，最终触发了一票否决。

根因：评分模型没有区分“核心路径失败”和“边角路径失败”。

这个画像和前面7个不太一样，前面的都是“检测结果本身错了”，这个是“检测结果没错，但评价规则太苛刻”。一个Skill的核心路径没问题，只是可选依赖在某些极端情况下不可用，这顶多算“中等级别缺陷”，不应该直接判0分。

我把“单项低于20%强制0分”改成了“单项低于20%且为核心维度（文件完整性、执行链路）才触发0分，非核心维度低于20%只记警告并扣分”。同时，执行链路测试开始区分“核心用例”和“扩展用例”，核心用例失败才触发0分，扩展用例失败只扣分。

3. 手工复核的实操流程：怎么识破“假0分”

体检器改完之后，第二轮体检的0分数量从11个降到了3个，这3个是真正的“实锤0分”。但二次复核那8个“假0分”的过程，本身比体检器还能说明问题——自动化检测工具只是在帮你把问题集中暴露出来，真正的“法官”还是人。

这节把复核流程拆一拆，方便大家把自己被误判的Skill也“捞”回来。

3.1 第一步：看原始日志，不看结论摘要

体检器第一版输出的是一个评分表，每个Skill一行，附上检测结论和扣分原因。这个设计看起来很Human friendly，但恰恰是它让我差点把几个好Skill给下架了——因为光看“扣分原因”几个字，你无法判断问题是出在Skill上还是出在检测环境里。

我复盘后定了一个规矩：体检报告里必须附上原始调用日志、进程退出码、标准输出和标准错误流。复核时先不看结论，直接从日志的开头读到结尾，观察报错发生的位置、上下文里有没有环境变量或路径信息。

具体怎么读？比如一个报错是FILE_NOT_FOUND，就得看这个文件路径是哪来的——是Skill内部写死的相对路径，还是从环境变量拼接出来的？如果是后者，抛出一个“读取的环境变量是None”的报错，那几乎可以断定是检测环境的问题。

3.2 第二步：手工构造最小复现场景

读完日志之后，第二步是“最小复现”。所谓最小复现场景，就是构造一个只包含“Skill + 最少的外部依赖”的环境来复现检测时的行为。

我以前验证一个Skill是否可用，喜欢直接用生产Agent环境去跑，这样最真实，但也最不稳——因为生产环境里的上下文、前置对话、资源占用都会干扰判断。最小复现是去掉所有干扰项，只留下最基本的运行条件。比如调外部API的Skill，就只起一个本地Mock Server，记录请求和响应，验证Skill的输出格式，不关心真实API能不能连通。

这一步是判断“假0分”的关键：如果最小复现场景下Skill能正常跑通，而完整检测环境下跑不通，那就说明问题不在Skill，而在检测环境。

3.3 第三步：逐项核对测试环境与生产环境

最小复现之后，还有一个问题要确认——如果Skill在生产环境是可用的，那体检器为啥没复现出生产环境的行为？

这不是运气问题，而是环境差异。我核对环境差异用的是三件套：依赖树的diff、环境变量的diff、工作目录的diff。

• 依赖树的diff：pip freeze对比体检环境和生产环境，看有没有缺包或版本不一致。
• 环境变量的diff：逐项对比关键环境变量，尤其是API Key、路径变量、代理配置。
• 工作目录的diff：检查Skill脚本中所有相对路径引用，确认它们在两个环境里指向的是不是同一批文件。

做完了这个核对，8个假0分里有6个当场就定位了原因，剩下2个靠的是“日志里的隐晦线索”才挖出来。所以“环境对齐”这件事，不是做完就完了，而是一个持续的动作。

3.4 第四步：用双盲指示词测试“输出质量误判”

如果前面三步都排除了环境问题，但输出质量维度的分数还是低，那就需要单独验证“评分模型本身”是不是太苛刻了。

我做了一个很土但很有效的办法——双盲指示词测试。让一个不知道Skill具体设计的助手，只根据Skill的说明书（SKILL.md和参数定义）来生成一份“合格输出样例”和一份“不合格输出样例”，再用体检器的校验规则去跑这两份样例，看规则能不能正确区分。

比如那个“写小说Skill”，如果体检器的校验规则连“合格样例”都判低分，那就是校验规则和真实需求不符。如果校验规则能正确区分两份样例，说明规则本身没问题，是Skill输出确实不符合预设规范——这时候才需要去改Skill的提示词或者后处理逻辑。

这一步的价值在于：它把“评分模型的问题”和“被评对象的问题”彻底分开了。

4. 常用排查技巧与误判速查表

前几节讲的是“为什么误判”和“怎么复核”，其实8个假0分背后对应的排查动作是可以沉淀成一整套方法论的。我整理了一张“假0分误判速查表”，也是我后来每次看到体检报告时先过一遍的清单。

4.1 六个先自查的问题

看到0分先别急着改Skill代码，按下面顺序自查一遍：

• 当前环境的依赖是否与Skill目录下的依赖声明一致？不一致就按声明装一遍，再跑。
• 测试时的输入样例是否与Skill当前版本的参数schema对齐？不对齐就更新样例。
• 检测时的超时阈值是否考虑了冷启动？冷启动比正常请求慢2到3倍是很正常的。
• 子进程有没有继承全部必要的环境变量？没有就透传，或者用mock值。
• 校验输出格式时用的是对象结构还是字符串包含？字符串包含最容易误杀。
• 低频分支里的可选依赖加载失败，是否被评分为致命缺陷？应该降级为扣分项。

这六个问题覆盖了前面8个画像里的大部分场景，如果你遇到0分，按顺序排查效率最高。

4.2 速查表：症状对应的处理动作

4.3 关于“体检查不出问题”的另外一件事

说完“误判”，还得提一嘴“漏判”。体检器解决了“把好的判成坏的”这个尴尬，但它也会放过“本来已经坏了但检测口径太宽松”的情况。你做体检器的时候，最难的不是规则怎么定，而是规则的口径怎么在“过严”和“过松”之间找到平衡。

我目前的策略是“两条腿走路”：体检器做硬性检查（文件完整性、Schema一致性、依赖可运行性），人工定期抽检做软性检查（输出质量、风格符合度、上下文适配感）。硬性检查能抓到“Skill一装上就跑不了”的伪货，软性检查能发现“装上能跑但总差一点意思”的平庸之作。两套并行，才是完整的Skill质量保障。

5. 这轮体检带给我的三个额外收获

除了修掉误判逻辑、把假0分捞回来之外，这轮体检还逼我做了三件平时根本懒得做的事。这三件事对Skill质量的提升反而比体检本身还大。

5.1 给每个Skill补上了 requirements.txt 和 .env.example

以前写Skill，依赖列表是散落在README里的，“反正装的时候自己手动装一下就行”。被体检器一跑，才发现依赖没有标准化的记录，检测环境根本不知道该装什么。

现在每个Skill目录里强制放两个文件：requirements.txt（Python依赖）和.env.example（环境变量模板）。前者让检测环境和部署环境有了统一的依赖安装入口，后者让环境变量的配置有了文档化的模板，等于给运维阶段留了“后门钥匙”。

5.2 给关键Skill建了“回归基线”

以前更新Skill是“改完就完”，不做回归验证。现在每个关键Skill都冻结了一份“基线输出样例”——更新Skill后直接跑一次对比测试，看输出和基线的一致性。这不是防止模型输出完全一样（也不可能一样），而是防止结构性字段发生变化。

比如“写小说Skill”的基线要求是输出包含“人物、场景、冲突、转折”四个核心段落标签，模型只要不是结构性缺失，具体措辞不同没关系。这样既能验证功能不退化，又不会被模型的随机性干扰。

5.3 体检器自己的代码也要“被体检”

最有意思的是，我把体检器也“体检”了一遍——拿它自己的检测规范去约束它自己的代码。因为我发现，体检器的逻辑如果不规范，它输出的报告会“稳定地误导你”。比如它自己的依赖没写全、自己的超时阈值不合理、自己的校验规则过拟合——这些毛病和Skill的毛病本质上一模一样。

现在体检器跑完一轮之后，会生成一个“体检器自检报告”，包含：本次体检中使用了哪些规则、每条规则的输入输出是否合法、哪些测试用例发生了内部异常（而不是被测Skill异常）。这样，当你看到一条“异常”时，能快速判断是检测对象的异常还是检测工具本身的异常。

6. 后续还能怎么扩展

这轮体检暴露出一个问题本来不在计划里，但现在我觉得它是下一阶段的工作重点——Skill体检的样本覆盖率。

目前每个Skill的测试用例数量是2到4个，都覆盖的是主路径。但对于那种依赖外部API或者长尾输入输出的Skill来说，2到4个用例远远不够。我现在在尝试给Skill维护一份“边界输入清单”——比如超长文本输入、空输入、特殊字符输入、非UTF-8编码输入等，让体检器在常规用例之外自动跑一轮边界输入测试。这能挖出很多之前完全没发现的“隐藏雷区”。

另外，Skill体检的结论不应该只是“0分还是100分”这种二元判断，而应该是一张“能力地图”——哪类调用场景表现稳定，哪类场景容易失败，API依赖的哪个环节最脆弱。我已经开始给体检报告增加“分类标签”，比如“代码生成类Skill在超长输入场景下表现弱”、“内容生成类Skill在特定风格约束下容易跑偏”这类可归类的结论。这样Skill的作者拿到报告后，能立刻定位到“该优化的是提示词结构、还是后处理逻辑、还是外部API的降级方案”。

还会不会出现新的“假0分”？我认为一定会。检测工具和被检测对象之间的博弈永远不会停止——Skill越写越复杂，检测规则就必须跟着细化，而细化过程中又会引入新的误判。这是“用工具改善工具”这个循环里注定的宿命，也是这个领域最有意思的地方。