为什么断言测试不够：skills-refiner 提升 Skill 质量
Anthropic 在 Claude Agent SDK 中引入 Skill 体系时，做了一个值得关注的架构选择：每个 skill 是一个可独立加载的目录，包含 YAML frontmatter、Markdown 指令主体，以及按需加载的 references、scripts 和 templates。这个三层渐进式披露（progressive disclosure）架构，把上下文工程（context engineering）的核心判断落到了工具设计层面。
metadata 层只加载名称和描述，用于 Claude 判断当前请求是否与该 skill 相关；instructions 层在 skill 被激活时载入；resources 层在任务需要时按需调用。每个 token 都有成本，多余的加载会挤压对话历史和其他 skill 的空间，降低整体系统的可靠性。
OpenAI 在 Custom GPT 和 Agent 体系中有类似的收敛趋势：单个 action 职责专一，接口用 OpenAPI schema 精确约束。两个框架在核心约束上达成了相似的共识：Skill 是能力的封装单位，不是 prompt 的堆砌。好的 skill 应该职责单一、边界清晰、可组合、可移植。
这些品质，是目前的测试测不出来的。
断言测试的结构性盲区
Anthropic 官方的 skill-creator 提供了创建-测试-迭代的完整循环：with-skill 与 baseline 的 A/B 对比、通过率和 token 消耗测量、基于断言的持续改进。它是功能验证层面设计完善的工具。
但断言测试有结构性盲区。一个 skill 可以通过所有测试用例，同时存在以下问题：
- 定位偏差：skill 的 description 是 Claude 决定何时激活它的唯一依据。描述过宽导致误触发，描述过窄导致该激活时被忽略。标准测试通常不会暴露这个问题，因为测试预设了 skill 已经被正确激活
- 上下文工程浪费：instructions 层包含了不必要的背景，把 Claude 已经内化的通用知识写了进去。测试依然通过，但这个冗余在生产环境里是真实的 context 成本
- 低可移植性：skill 的核心逻辑依赖了特定工作流或工具调用链。在设计者自己的 repo 里运行完美，到了另一个人的环境里就失效
- 边界模糊：skill 的职责范围没有清晰界定，与同一 repo 里的其他 skill 存在重叠，或者对某些输入类型默默降级而不通知用户
断言测试通过，证明 skill 在已知场景下按预期执行。它证明不了 skill 设计是否正确。这两个问题是不同的。
skills-refiner 是什么
skills-refiner 是一个专门处理上述盲区的 Agent Skill 评估工具，通过 skills CLI 安装，在支持 skills 的 agent 环境（Claude Code、Cursor、Codex、OpenCode 等）中直接调用。
skills-refiner 并不重复 skill-creator 的测试职责，而是补充测试覆盖不到的那一层：设计判断。
分析框架围绕六个维度展开：
- 定位：skill 真正解决什么问题，边界在哪
- 机制：哪些设计选择真正驱动了它的行为
- 价值：什么是真正强的和可复用的，什么只是表面修饰
- 风险：什么是脆弱的或难以维护的
- 改进：具体的提升方向
- 集成：当需要把 skill 吸收到另一个 skill/skill仓库时，哪些可以直接用，哪些需要重新设计，哪些应该放弃
它的工作分为两个阶段，对应三个核心动作。
第一阶段：诊断与精炼（Diagnose & Refine）
诊断的对象可以是一个Skill仓库、单个 skill、工作流框架，或者 eval 集。诊断不是打分，而是定位这个 skill 的真实状态：它真正解决什么问题、边界在哪、哪些设计选择有实质作用、哪些只是表面修饰、哪些是隐患。
精炼是诊断的直接下游。发现之后就要判断：哪些应当保留，哪些应当改进，哪些应当简化或重新划定范围，哪些应当去掉。这不是风格建议，是设计决策。skills-refiner 的名字里强调的是 refine，不是 audit——精炼是目的导向的，refine 的是结果，不只是列问题。
第二阶段：提取与整合（Extract & Integrate）
当给出目标Skills仓库（target_repo）时，第二阶段启动。这一步关注的是这个 Skill/Skills仓库对目标仓库有什么价值——哪些部分可以直接采纳，哪些需要重新设计才能使用，哪些应当放弃，以及整合之后目标仓库的哪些部分面临最大的风险。
整合输出的是可操作的计划：最小可行整合路径和高价值增强方向。
目的决定标准
这个框架有一个不妥协的核心立场：评估工具应该知道自己在评估什么。
工程和工作流类的 skill 需要被审查结构严谨性、上下文工程质量、可维护性和跨仓可移植性；研究分析类的 skill 需要被审查推理质量和证据纪律；写作或教学类的 skill 需要被审查清晰度和输出质感。用工程标准去诊断一个创意写作 skill，结论通常是错的。
同样的原则适用于 eval 集：当诊断对象是一个 eval 集时，skills-refiner 最关注的不是测试通过了多少，而是这个 eval 集有没有测到真正重要的东西——覆盖面是否触及了真实的风险面，断言是否能区分好答案和凑合的答案，边界场景有没有被遗漏。
证据优先原则
skills-refiner 的另一个核心原则是证据优先原则（evidence discipline）：分析必须区分三类判断：
- 直接证据：文件中直接可读的内容
- 合理推断：基于可见证据的有理由但非确定的判断
- 未解决的不确定性：证据不足以支撑的问题，应明确标注而不是被自信的措辞掩盖
这个区分，是针对 LLM 分析输出中一个普遍存在的问题而设计的：用事实的语气表达猜测，让读者无从判断哪些结论可信。在 skill 审计场景下问题更具体——一个 skill 可能只提供了部分文件，审计结论应该诚实地说清楚「我看到了什么，我推断了什么，我还不知道什么」。
与 skill-creator 的分工与协作
skill-creator 拥有创建、A/B 测试、断言迭代、description 优化和打包分发的完整循环。skills-refiner 在功能测试之后介入，回答另一类问题：这个 skill 设计是否正确？它的定位是否准确？它到另一个人的 repo 里还能工作吗？上下文工程有没有浪费？
典型路径：
- 用 skill-creator 创建并迭代一个 skill
- 测试通过后用 skills-refiner 做设计级诊断与精炼
- 把明确的改进点带回 skill-creator 做下一轮迭代
- 当需要把一个现有 Skill仓库的成果整合进另一个项目时，启动整合阶段，得到具体的提取和集成计划
苏米注：测试告诉你 skill 做了什么；诊断与精炼告诉你它设计得是否正确；整合告诉你它在新的系统里是否还成立。三者覆盖了 skill 生命周期里功能测试触不到的全部设计层面。
安装与使用
安装：
npx skills add yknothing/skills-refiner使用示例：
# 诊断与精炼一个Skill/Skill仓库
> 使用 skills-refiner 评估此 skill/skill仓库
# 评估并整合到目标 repo
> 使用 skills-refiner 评估此 skill/skill仓库，并整合到目标 skill/skill仓库 [名称] 中适用场景
skills-refiner 适合以下场景：
- 用 skill-creator 完成了一个 skill，想在分发前做设计层诊断与精炼
- 想把某个 Skills仓库吸收进自己的项目，需要判断哪些部分可用、哪些需要改造、哪些应当放弃
- 维护多个 skill 的仓库，需要定期评估整体结构的健康程度
- 想评估一个 eval 集的质量——它有没有真正覆盖 skill 的风险面
它不生成 assertion 测试，不运行 A/B 对比，不优化 description 的触发精度，不负责打包分发。这些边界是刻意的，目的是把判断层的事做好，把执行层的事交给更合适的工具。