技能精简与技能债长期治理

目标是让技能库长期保持精简、清晰、零沉积：每种能力只有一个技能的简介负责触发，每个留下的技能只保留当前有效的核心流程（细节进 references/、确定性步骤进 scripts/）。默认保留，有证据才动。

1. 证据

python <本技能目录>/scripts/skill_evidence.py --days 45

脚本以 0 token 只读扫描本机共享技能目录（~/.agents/skills、~/.claude/skills、~/.codex/skills、~/.cursor/skills、~/.pi/agent/skills 及可选的网关 library.json），统计每个技能近 45 天在各客户端会话记录中被实际读取的会话数、简介 UTF-8 字节数、SKILL.md 行数、分发去向，并标记 frontmatter 坏、简介>500B、正文>500行 或 残留标签 告警。另外核查两处：

• 客户端停用清单（若有维护全局停用表，如 skills-disabled.json）。
• 技能来源：来自 ~/.agents/.skill-lock.json、上游克隆目录或 CLI 自动生成的技能，工具升级重装时会被覆盖。这类技能能撤分发就不直接改正文；非改不可的，在记录里写明重装后如何重做。

这一步完成的标准：每个待审技能都有用量、简介字节数、正文行数、来源四项客观数据。

2. 判断

每个技能先用一句话写下它的精髓：它独有、别的技能做不到的能力。然后只看四类问题：

• 重复：两个技能能接同一句请求时，用得多或更通用的那个当入口。其余技能的独有能力写进各自简介（"X 用本技能"），重叠部分在简介里指回入口。精髓已被入口完全覆盖、且长期零使用的，撤下分发（保留原文件备查）。
• 失效：依赖的工具、路径或服务已经退役。只坏了一两行就改那几行，核心流程已无使用场景才撤下。
• 简介：超过 500 UTF-8 字节、没写"何时不用"，或抢了别的技能的触发词，就按 writing-for-agents 重写：先写干什么、什么时候用，再写哪些边界情况让给谁。
• 体量、内容债与副本漂移：在用技能的 SKILL.md 超过 500 行时，按 writing-for-agents 把长参考表拆进 references/；每次精简轮巡 1–2 个高频在用技能，清掉正文里的过期命令、退役基建引用、带日期的决议经过（只留当前做法与理由），把重复机械步骤下沉进 scripts/；若云端/记忆库（如 OpenViking viking://~/skills）存有同名副本且内容漂移，同步更新或清退重复副本。不重写已经有效的规则。

低频但独有的技能留着（例如特定文件排版、专用硬件控制、低频远控）。本人近期亲手安装的也留着。拿不出具体证据（文件、行号、命令输出、会话用量）的不动。正文只修过期的行，不为改写法而重写。

3. 执行

1. 动手前把涉及的技能目录与分发配置备份到带日期的备份目录。
2. 撤分发：使用你所用的技能管理器撤下对应客户端链接（如网关库命令、移除客户端 skills/ 软链，或将名称加入客户端停用清单）。注意部分客户端会原生扫描 ~/.agents/skills，仅撤软链对原生扫描目录不生效，需配合停用清单或移至归档目录。
3. 改简介和过期行。改完对全部 SKILL.md 再跑一遍 skill_evidence.py，确认所有 frontmatter 解析正常且告警清零。
4. 不直接删除仍有参考价值的源文件；不擅自重新启用本人已停用的技能。

4. 记录

结论写进当次清理记录：撤了什么、改了什么、各自的证据与理由、备份回退位置、上游重装后需重做的项。一次精简最多处理约 10 个技能，避免单次改动面过大。