导读

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 分别解决什么

前两个是分析类，通过自然语言触发，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 为准）。

但这些验证本身也有边界。沙箱测试能证明脚本在模拟拓扑下行为正确，无法证明所有 agent 平台的运行时发现规则。锚点评估能帮助保持判断质量，无法替代真实团队场景里的使用反馈。

治理系统要建立证据链，也要标注证据链的边界——这个原则同样适用于治理工具本身的测试策略。

Agent Skills是新的软件资产，治理是核心痛点

Agent Skills 正在变成一种新型软件资产。它们不是传统意义上的库，也不是纯文本 prompt。它们介于文档、工具、流程和上下文工程之间，会被安装、分发、更新、软链接、复制、修改、废弃。

只要它们长期存在，软件工程里熟悉的问题就会出现：版本、来源、拓扑、漂移、冲突、安全、可见性、清理、审计。

一个 skill 的时代，关键是把它写好。

一套 skills 系统的时代，关键是知道它们从哪里来，在哪里可见，有什么证据，哪些值得信任，哪些需要继续观察。

skills-refiner 2.0 的价值就在这里：它把 Agent Skills 从"装完就忘"的个人配置，推向可审计、可解释、可治理的本地基础设施。

它不是让 AI 代替人做决定。

它是让 AI 和人终于有足够清楚的事实，去做一个不草率的决定。

skills-refiner 2.0 如何安全与使用？

如何安装

通过 skills CLI 安装（具体支持的 agent 以该 CLI 文档为准）：

npx skills add yknothing/skills-refiner

安装后会在你的 agent 目录里注册四个 skill：skills-refiner、skills-appreciation、skill-hygiene、skill-debug。

克隆本仓库做开发或贡献时，可在仓库根目录使用包装脚本（转发到 skills/skill-debug/bin/skills-refiner-doctor.sh）：

bash bin/skills-refiner-doctor.sh --help

若脚本解析不到默认工具树，可设置环境变量 SKILLS_REFINER_TOOLS_ROOT 为同时包含 skill-debug/ 与 skill-hygiene/ 的目录（目录布局与 ~/.agents/skills 一致）。

如何使用？

建议： 安装后，日常优先用只读的 skills-refiner-doctor.sh 一键拉齐「可见性（probe）+ canary 日志摘要（dashboard）+ hygiene 现场扫描」；会改磁盘上 SKILL.md 的常见路径只有 skill-trace 的 canary 注入/移除——务必显式确认后再跑。设计原则、能力边界与「2.0 在解决什么问题」见姊妹篇 skills-refiner 2.0。

一键健康检查（推荐）

想一次性看完「当前目录可见的 skills」「最近 canary 记录」「全局安装拓扑与健康信号」，用只读聚合脚本 skills-refiner-doctor.sh：顺序执行 probe → dashboard → skill-scan.sh --no-write（终端 hygiene，不落盘 ~/.agents/skills-report/scan-*.json）。不会注入/移除 canary，不会改任何 SKILL.md。

bash ~/.agents/skills/skill-debug/bin/skills-refiner-doctor.sh

交给 agent 做解读时，用 JSON 整包（schema 以脚本输出为准，如 skills-refiner.doctor.v1）：

bash ~/.agents/skills/skill-debug/bin/skills-refiner-doctor.sh --json

从本仓库克隆开发时，可用根目录包装脚本（等价转发到 skills/skill-debug/bin/）：

bash bin/skills-refiner-doctor.sh --help

或直接调用仓库内脚本：

bash skills/skill-debug/bin/skills-refiner-doctor.sh --json

若脚本解析不到默认工具树，设置 SKILLS_REFINER_TOOLS_ROOT 为同时包含 skill-debug/ 与 skill-hygiene/ 的目录（布局同 ~/.agents/skills）。

常用参数：--cwd 路径（probe 视角）、--days N（dashboard 时间窗）、--with-trace-status（只读附加 skill-trace.sh --status）。

与 skill-probe.sh --doctor 的区别： probe --doctor 在 probe 报告末尾追加原生信号摘要、激活日志简析，并仅在磁盘上已存在 hygiene 的 scan-*.json 报告时引用最近一次结果；不会像 skills-refiner-doctor.sh 那样当场执行 skill-scan。需要「只读但含最新 hygiene」时优先用 doctor 脚本。

分析类：用自然语言触发

审查一个 skill 仓库

打开你想分析的仓库（或把内容粘贴进上下文），然后对 agent 说：

用 skills-refiner 分析这个仓库。

agent 会返回结构化报告，包括定位判断、优缺点、以及前三项优化建议。

审查单个 skill 文件

用 skills-refiner 分析这个 skill。重点关注边界清晰度、可复用性和上下文工程质量。

整合到另一个仓库

如果你想把某个 skill 仓库的设计思路引入自己的项目：

用 skills-refiner 分析这个仓库，目标仓库是 yknothing/prodcraft。

skills-refiner 会先完成设计审查，再给出兼容性分析和具体的整合方案。

配合 skill-creator 使用

用 skill-creator 创建 skill 并通过测试后，让 skills-refiner 做设计层面的审查：

我刚用 skill-creator 创建了这个 skill，所有测试都通过了。用 skills-refiner 审查它的设计质量——重点关注结构、边界、上下文工程，以及测试可能遗漏的问题。

写解析文章

如果你想把审查结果变成一篇可读的文章（比如向团队解释某个 skill 的设计逻辑）：

用 skills-appreciation 分析这个 skill。我想要一篇深入但易读的解析，帮助团队理解它为什么被设计成这样。

治理类：脚本收集事实，AI 解读

JSON 路径依赖本机已安装 jq（缺失时脚本会报错或提示）。

扫描本地已安装的 skills

bash ~/.agents/skills/skill-hygiene/bin/skill-scan.sh

脚本会扫描 ~/.agents/skills/、~/.claude/skills/、~/.cursor/skills/、~/.codex/skills/ 等常见安装目录（完整集合与字段以 skills/skill-hygiene/SKILL.md 与 --help 为准），输出每个 skill 的原始路径、修改时间、内容哈希、来源信号、风险指标等结构化事实。

扫描完成后，把结果交给 agent 解读：

用 skill-hygiene 评估这份扫描结果，给出改进建议。

也可以用 JSON 格式直接输入 agent：

bash ~/.agents/skills/skill-hygiene/bin/skill-scan.sh --json

常用选项

# 调整过期阈值（默认 180 天）
bash ~/.agents/skills/skill-hygiene/bin/skill-scan.sh --stale-days 365

# 只输出到终端，不写报告文件
bash ~/.agents/skills/skill-hygiene/bin/skill-scan.sh --no-write

查看哪些 skills 在当前目录可见

bash ~/.agents/skills/skill-debug/bin/skill-probe.sh

从当前工作目录出发，列出本诊断所扫描的发现面上可见的 skill 文件，并标注同名冲突和失效软链接。平台真实加载顺序可能与文件系统视角不同，以 probe 输出中的说明为准。

# 指定项目目录
bash ~/.agents/skills/skill-debug/bin/skill-probe.sh --cwd ~/projects/my-app

注入 activation canary（激活 canary），观察 agent 是否执行了某段指令

Canary 是一条轻量 bash；若 agent 按 skill 中的指令去执行它，事件会写入本地 JSONL。它只能证明「这段 bash 曾被执行」，不能证明 skill 被完整加载或遵守。注入/剥离会修改磁盘上的 SKILL.md，仅在用户明确要求时使用（与 skill-debug / skill-hygiene 的 SKILL guardrails 一致）。

# 向目录下所有 skills 注入 canary（会改 SKILL.md）
bash ~/.agents/skills/skill-debug/bin/skill-trace.sh --inject-dir ~/.agents/skills/

# 观察一段时间后，查看 canary 日志摘要
bash ~/.agents/skills/skill-debug/bin/skill-dashboard.sh

# 移除 canary（会改 SKILL.md）
bash ~/.agents/skills/skill-debug/bin/skill-trace.sh --strip-dir ~/.agents/skills/

注意：日志只能证明「canary 指令曾执行」，不能证明发现、加载或输出质量；优先信任各 agent 的原生遥测（若已配置）。

probe 的 --doctor 附加段（≠ skills-refiner-doctor.sh）

bash ~/.agents/skills/skill-debug/bin/skill-probe.sh --doctor

在常规 probe 输出之后追加：原生信号（如 Claude Code OTel 环境等，以脚本为准）、激活日志简析；若已存在 hygiene 的落盘报告 ~/.agents/skills-report/scan-*.json，则引用最近一次结果做交叉提示。不会当场运行 skill-scan——需要「含最新 hygiene 的只读快照」请用上一节的 skills-refiner-doctor.sh。

典型工作流

场景：使用已安装的 skills-refiner skills,帮我整理本地的全局 skills，分析哪些值得保留

可以先跑只读聚合（当场跑 hygiene 终端扫描，默认不写 scan-*.json 报告文件；与下面分步相比更省事）：

bash ~/.agents/skills/skill-debug/bin/skills-refiner-doctor.sh
# 或输出一整份 JSON 再给 agent：
bash ~/.agents/skills/skill-debug/bin/skills-refiner-doctor.sh --json

需要分步控制或自定义参数时再拆开：

# 1. 探测可见性
bash ~/.agents/skills/skill-debug/bin/skill-probe.sh

# 2. 查看激活记录
bash ~/.agents/skills/skill-debug/bin/skill-dashboard.sh

# 3. 扫描安装态健康状况
bash ~/.agents/skills/skill-hygiene/bin/skill-scan.sh --json

# 4. 让 agent 基于以上结果给出判断
用 skill-hygiene 评估这份扫描结果，结合 canary 观测与发现面结论，给出保留、观察和清理建议。

场景：我刚创建了一个 skill，想知道设计有没有问题

用 skills-refiner 分析这个 skill。

场景：我想把某个开源 skill 仓库的设计引入自己的项目

用 skills-refiner 分析这个仓库，目标仓库是 [你的仓库]。