技能集瘦身 · Agent 技能路由体检
核心命题：技能不是装得越多越强。超过某个数量后，每多装一个，Agent 整体变笨一点——因为瓶颈从「能力」转移到了「路由」。
一、这不是感觉，是有量化实测的
| 数据 | 来源 |
|---|---|
| 89 个 skill 时，工具调用成功率从 100% 基线跌到 55.6% | Claude 插件可靠性评测（2026） |
| 工具数量接近 152 个后模型开始不稳定，工具选择准确率 43% → 14% | 上下文腐烂实测（2026） |
| 生产环境任务失败率 33%，主因是记忆/状态而非幻觉 | Stanford AI Index（2026） |
| 活跃技能 5–8 个为最优区间 | 同上 |
| 每步 95% 可靠的 Agent，10 步后只剩约 60% | Agent 可靠性分析（2026） |
典型事故形态：
- 写博客触发了安全审计——两个技能的描述边界不清
- 飞书消息发到了企业微信——同名类技能抢路由
- 同一个技能装了两份，Agent 每次随机挑一个，其中一份是旧版
根因归一：模型在调用前要先"读懂"所有技能的描述。描述越多、越像、越含糊，路由准确率越低。
二、三类路由失效
| 类型 | 现象 | 可否机器判 | 本技能怎么做 |
|---|---|---|---|
| A 规模衰减 | 技能总数过多，整体准确率下降 | 可判 | 阈值告警（30 警告 / 50 高危） |
| B 重复安装 | 同一技能装了多份，版本不一致 | 可判 | 规范化 id 比对 |
| C 语义冲突 | 两个技能描述太像，模型分不清 | 近似判 | 字符 n-gram + 触发词重叠，给相似度 |
| D 描述缺陷 | 无 description / 太短 / 无排除条款 / 触发词缺失 | 可判 | 逐条规则扣分 |
> C 类只能近似判。 脚本用字符 n-gram 的 Jaccard 相似度给线索，阈值仅供参考，冲突对必须人工确认。不假装能判语义。
三、五步工作流
S1 扫描
python3 scripts/skill_scan.py # 扫默认目录
python3 scripts/skill_scan.py ~/.workbuddy/skills/ # 指定目录
python3 scripts/skill_scan.py <dir> --json # 结构化输出
python3 scripts/skill_scan.py <dir> --strict # 有高危项时退出码 1（可接 CI）
S2 判规模
看总量。>50 高危、30–50 警告。规模问题的解法不是"删到 8 个"，而是分常驻与按需两层。
→ references/size-policy.md
S3 判重复
先看重复安装——这是性价比最高的一类，删掉立刻见效，且零风险。
S4 判冲突
按相似度从高到低处理。≥0.45 的强冲突优先：合并、或拉开触发词。
→ references/routing-failure.md
S5 开处方（本技能的产出，不只是发现）
对每个低分技能，直接产出改写后的 description 草稿，按模板填入触发词、触发场景、不适用于三段。
→ references/description-craft.md
四、健康分规则（权重按「是否直接导致路由事故」排序）
| 规则 | 级别 | 扣分 | 为什么这个权重 |
|---|---|---|---|
| 无 description | 致命 | 40 | 路由完全无依据 |
| description < 40 字 | 待核 | 30 | 信息量不足 |
| 无「不适用于」 | 待核 | 25 | 没有负边界，必然误触发 |
| 重复安装 | 致命 | 25 | 每次都可能调到旧版 |
| 缺 name 字段 | 致命 | 20 | frontmatter 不完整，发布即失败 |
| 每对冲突 | 待核 | 12/对（最多 3 对） | 抢路由 |
| 触发词问题 | 提示 | 15 | 命中面太窄或不可控 |
| 泛词过多 | 待核 | 10–20 | 「帮我/处理/各种」会抢别人的路由 |
为什么「无排除条款」权重这么高：实测中的误触发事故（写博客触发安全审计）几乎全是缺负边界造成的。正向描述列不完该做什么，一句"不适用于"能挡掉大部分。
五、铁律
- 先删重复，再调描述。 重复安装是零风险高收益，优先做。
- 每个技能必须写「不适用于」。 没有负边界的技能等于在抢所有人的路由。
- 泛词是路由毒药。 「帮我处理各种 XX」会被模型理解成"什么都能干"。
- 常驻 5–8 个，其余按需加载。 不是全部删掉，是分层。
- 装新技能前先跑一次扫描。 预防比清理便宜。
六、边界（本技能不做什么）
- 不跑任务、不评测成功率。 只读 frontmatter 做静态诊断，不测模型实际路由行为。
- 语义相似度是近似值。 阈值 0.30/0.45 是经验值，不是精确判据；所有冲突对需人工确认。
- 不自动删除任何东西。 脚本只读不写，删不删由人决定——这是刻意设计，不是功能缺失。
- 不管 MCP 服务器的连接与鉴权。 只处理技能描述的路由质量。
七、脚本
scripts/skill_scan.py，零依赖 Python 3 标准库。
输出五段：规模诊断 / 重复安装 / 语义冲突矩阵 / 逐个健康分 / description 改写处方。
退出码：0 通过 · 1 存在高危项（仅 --strict）· 2 用法错误。
定位是筛子不是法官：能从 frontmatter 查到的事实查到位，语义判断明说是近似，绝不为了显得有用而编造判定。
完整真实扫描报告见 assets/example/（对 54 个技能的实际诊断，含重复安装与 15 对冲突）。
