skills-refiner 2.0:如何做好Skills的系统化治理

 

导读

skills-refiner 2.0 在 1.0 的「设计层审计」之上(使用skills-refiner提升skill质量),把问题扩展到已安装 skills 的拓扑、来源、本地证据与保守治理;原则仍是 「AI judges, scripts collect」,即由脚本收集可验证事实,AI 解释,人来判断和拍板。

skills-refiner 1.0 的出发点是:skill-creator 能帮你创建和测试 skill,但测试通过不等于设计正确。一个 skill 的定位、边界、上下文工程、可移植性和整合价值,需要另一层判断。

当你只有一个 skill,核心问题是它设计得好不好。当你有几十、上百个 skills,它们分布在 .Agents/skills、.claude/skills、.cursor/skills、.codex/skills,有些是原始来源(以 ~/.agents/skills/ 为主控目录),有些是软链接(指向原始来源的快捷方式,用于在各个 agent 目录里分发),有些是各个 agent 目录里独立安装的,有些是旧版本残留——问题就变了。

真正的问题不再是一个 skill 设计得好不好,而是这个 skills 系统是否仍然可理解、可观察、可治理。

这就是 skills-refiner 2.0 的设计目标。

Skill 变成系统以后,问题的性质变了

单个 skill 的质量问题,和一组 skills 的治理问题,是两类性质不同的问题。

单个 skill 的核心问题是设计质量:触发条件是否清楚,指令是否克制,是否太宽泛,是否值得长期维护。测试只能证明 skill 在已知场景里能跑通,却不能证明定位正确、边界清楚、上下文工程合理。一个通过测试的 skill 仍然可能太宽、太模糊,或者根本不值得维护。

但当 skills 变多、分布在多个目录之后,你会遇到另一类问题:

  • • .claude/skills/foo 是独立安装的 skill,还是指向 ~/.agents/skills/foo 的软链接?
  • • 两个同名 skill 是同一内容,还是来自不同仓库、实际上已经分叉?
  • • 一个六个月没更新的 skill 是稳定在运行,还是引用了已经废弃的工具?
  • • 没有本地 canary 记录的 skill,是从没被触发,还是 agent 根本没有加载它?
  • • 全局安装目录和仓库源码是否已经悄悄漂移?

这些问题的本质是软件工程里熟悉的拓扑、来源、版本、漂移问题——只不过发生在 Agent Skills 这种新型资产上。

核心设计原则:AI judges, scripts collect

skills-refiner 2.0 没有把治理做成自动清理器。它的核心原则是:

AI judges, scripts collect.

脚本负责收集事实,AI 负责解释事实,人做最终决定。

这个分工背后有一个清晰的判断:某些问题脚本能准确回答——哪些目录存在 SKILL.md,哪些软链接断了,原始路径是什么,内容哈希是否相同(可能被隐式地修改),元数据头(skill 头部的结构化描述,agent 用来决定是否加载该 skill)是否完整,是否出现 curl | bash 这类风险信号,canary 与相关本地 JSONL 里记录过哪些事件。这些都是文件系统可以证明的事实。

另一些问题脚本不该回答:这个 skill 是否应该删除?180 天没更新是不是过期了?零 canary 记录是不是异常?某个体积很大的 skill 是过度膨胀,还是本来就是一份必要的参考资料?这些判断需要结合使用场景、团队习惯、来源可信度和实际工作流。硬编码规则很容易制造误报,而误报在治理工具里比"什么都不说"更危险——它会给错误决定披上"自动化"的外衣。

AI 在有结构化事实输入时更适合做这类专家判断,但最终动作应该由人确认。清理是治理的结果,不是起点。

两层能力:分析与治理

2.0 在原有设计审计基础上,增加了一层面向已安装 skills 系统的治理能力,共四个 skills。

四个 skill 分别解决什么

Skill
解决的问题
skills-refiner
审查一个 skill 或 skill 仓库的设计质量
skills-appreciation
把设计判断转成可读的解析或博客文章
skill-hygiene
扫描本地已安装 skills 的健康状况
skill-debug
哪些 skills 在本诊断的发现面上可见、以及 canary 的本地 JSONL 观测记录

前两个是分析类,通过自然语言触发,agent 负责完成分析。后两个是治理类,通过 shell 脚本收集事实,再让 agent 解读。

第一层:分析与解读

skills-refiner 继续负责单个 skill 或 skill 仓库的设计审计——定位、结构、上下文工程、边界、复用性、成熟度。判断一个 skill 是应该保留、简化、拆分,还是直接拒绝。

skills-appreciation 把这种判断转成可读、可教学的解释。它不是营销文案生成器,而是帮助读者理解一个 skill 或 skills 系统为什么这样设计,哪些思路值得学习,哪些只是局部习惯。

第二层:治理与可观测性

skill-hygiene 负责安装态扫描。它区分四类对象:原始 skills(在 ~/.agents/skills/ 里的主控目录)、软链接分发(各 agent 目录里指向原始来源的软链接)、独立安装的 skills(某个 agent 目录里自行安装、不经由主控目录的 skill)、项目级 skills(项目仓库内部的 skills,属于项目上下文)。扫描结果包含内容哈希、修改时间、来源信号、风险指标、同名冲突、失效软链接等结构化事实,供 AI 判断。

skill-debug 提供三层本地证据机制:skill-probe 从当前工作目录出发,枚举「可能被本诊断扫描到的」本地 skill 发现面(含常见 agent 与项目内路径,与真实运行时发现规则可能不完全一致,以脚本说明为准);skill-trace 向 SKILL.md 可逆地注入激活 canary(README / SKILL 中亦称 activation canary:一条轻量 bash,若 agent 按指令执行则把事件追加到本地 JSONL);skill-dashboard 读取该日志,按 skill 身份聚合 canary 观测结果。

此外,skills-refiner-doctor.sh 在终端或 --json 模式下顺序编排上述只读路径:一次跑完 discovery 报告、dashboard 摘要,以及 hygiene 的现场扫描(终端模式用 skill-scan.sh --no-write,不落盘 ~/.agents/skills-report/scan-*.json;需要生成该目录下的 JSON 报告时再单独跑默认的 skill-scan.sh(勿加 --json/--no-write)。只要 stdout 的机器可读 JSON、不要落盘报告文件时用 skill-scan.sh --json,以 skill-scan.sh --help 为准)。它与 skill-probe.sh --doctor 不同:后者在 probe 末尾附带原生信号摘要、激活日志简析,并仅在已存在 ~/.agents/skills-report/scan-*.json 时引用最近一次 hygiene 落盘结果,不会替你当场执行 skill-scan。

这四个 skills 与 doctor 脚本组合的典型工作流:先只读体检(doctor 或分步 probe / dashboard / scan),必要时再考虑 canary 注入,最后由 AI 基于证据给出建议,人做确认。

除四个可触发的 skill 外,仓库还提供只读聚合脚本 skills-refiner-doctor.sh(probe → dashboard → hygiene,不修改任何内容),作为日常体检入口。

拓扑比数量更重要

"装了太多 skills"只是现象,真正的问题是拓扑不可理解。

设想一个常见场景:你运行扫描器,发现 ~/.claude/skills/ 里有 12 个 skill 目录,~/.cursor/skills/ 里又有 10 个,部分名字重复。如果扫描器把所有软链接都当作重复,就会误报大量"冗余";如果它把软链接和真实目录一视同仁,就会漏掉真正需要关注的同名冲突——两个名字相同但来自不同仓库、内容已经分叉的 skill。更危险的情况是把工作区里某个 GitHub 项目仓库当成坏掉的全局 skill,或者把所有同名 skill 合并成一条记录。

错误的拓扑模型给出错误建议,错误建议比没有建议更有害:它给误删、误归档披上了"自动化治理"的名义。

2.0 的标识模型因此不只看 skill 名字,而是结合原始路径和内容哈希来识别 skill 标识。这样,同一个原始来源通过多条软链接分发时不会被误算成重复;同名但不同来源、不同内容的 skill 也不会被混在一起。这个区分不是为了增加复杂度,而是为了让治理工具的输出足够可信,真正能拿来用。

可观测性是Agent的结构性难题

Agent Skills 的可观测性是一个结构性难题。普通用户很难知道 agent 是否真的发现了某个 skill、是否加载了它、是否遵守了它的指令、它对输出质量贡献了多少。

2.0 没有假装能解决这个问题。

skill-debug 的 canary 机制原理是:向 SKILL.md 注入一条标准的 bash 指令,把事件写入本地 JSONL(默认在 ~/.agents/debug/activation.jsonl,以脚本为准)。如果 agent 在使用某个 skill 时执行了这条指令,记录就会出现。如果记录没有出现,则可能有几个原因:1)可能是 skill 没被发现;2)也可能是 agent 跳过了该段指令;3)也可能是遵守了 skill 但未执行 canary。

这条边界必须写清楚:canary 只能统计 「执行了注入的 bash 指令」 这个事实,不能证明 skill 被发现了、被正确加载了、被完整遵守了,更不能量化对输出质量的影响。这些信息应该优先依赖平台原生的运行时遥测(如 Claude Code 的 OpenTelemetry)。没有原生遥测时,canary 只能作为代理证据。

承认这个边界的目的是为了说明,2.0 比许多"智能治理工具"更可信的地方是:它清楚地知道自己能证明什么,也知道自己不能证明什么。一个治理工具如果对自己的能力声称太多,就会在用户最需要判断的地方制造虚假信心。

作为治理工具,需保持克制

skills-refiner 2.0 在每一个具体的设计决策里都有对 「度」 的考虑。

这个工具设置了一个默认的过期告警阈值(180 天),可以按需调整。当然了,大半年没更新的 skill 可能已经非常稳定,也可能引用了过时的工具链。工具只报告事实,不代替你得出结论。

它不把"没有 canary 记录"当作"没被使用"。零 canary 观测只是一条观察,不是删除建议。skill 可能在没有触发 canary 的情况下被 agent 执行,也可能从未被需要过。两者在本地证据上无法区分。

工具会谨慎判断软链接是否是重复项。软链接是当前 Agent Skills 安装模型里被有意设计的分发机制,不是冗余。如果你本地有维护自己的Skills仓库并通过软链接方式部署了,那么本工具不会误差为重复。

它也不自动清理。安全的治理流程应该是:先扫描,再解释,再给出建议,最后由人确认。删除、归档、重构这类动作应该带着证据发生,而不是被某条规则静默触发。

工程化的核心体现是建立边界

2.0 的实现包含 shell 集成测试和锚点评估。前者覆盖 hygiene 扫描、discovery probe、canary 注入/剥离、dashboard 聚合,以及只读 skills-refiner-doctor.sh 在隔离 HOME 下的烟测(见 skills/skill-debug/tests/test-doctor.sh 等);后者在 evals/ 中维护分析类 skills 的锚点案例与量表(规模以仓库 README 为准)。

但这些验证本身也有边界。沙箱测试能证明脚本在模拟拓扑下行为正…

— 以上为试看内容(约 40%),开通会员后阅读全文 —