技能进化建议（evolve-skills）

你要解决的事

技能库的问题是两头都没人管：

一边是该建没建 —— 同一个动作做了第三遍，谁也没想起来把它固化成技能； 一边是该改没改 —— 老技能带着过期的判据和触发不了的 description，继续被调用。

用户隐约觉得"该沉淀点什么"，但说不清是哪件事、也说不出该改哪个技能。

你要把他从「模糊的感觉」带到「一份分好类的建议清单，逐条确认或忽略」。

产物：建议清单（类型｜对象｜依据｜成本｜建议动作）。人确认的那条，才进入创建或更新流程。

底层原理：读你自己的历史会话。 重复的动作、被纠正的那句话、点名了却没生效的技能——这些痕迹都留在本地会话转写里（见第 1 步）。 判断依据不来自"我觉得"，来自"会话里确实这么发生过"。

这个技能为什么存在

• 解决什么问题：技能库只增不减会退化——不是玄学，有实测：语料规模增长 21.6 倍后， 检索 Top-1 从 0.778 掉到 0.356（−42.2pp）。更常见的是该建的没建： 一个动作重复到第四次，成本已经付了四遍，仍然没人把它固化下来。
• 不解决什么（边界）：不出手改。本技能只产出建议，落盘动作（创建新技能 / patch 已有技能） 由人在确认后走各自流程。也不做配置层体积瘦身——那是另一件事。
• 决策依据：三条，各有出处，否决了两个看起来更省事的方案：
  1. 触发用行为信号，不用自然语言口令 —— 检索不到任何一手来源支持 「用户说了某句话」作为沉淀判据；现存系统的判据全部基于行为信号（失败 / 重复 / 评测分数 / 遥测）。 否决了"用户喊一句'沉淀一下'就动手"。
  2. 建议必须带依据 —— 说不出命中哪条信号的，不进清单。否决了"感觉这个值得建"。
  3. 改造之前先有评测 —— 有对照实验：让模型自己写技能相对无技能基线是 +0.0pp； 人写是 +16.2pp。否决了"改完看着更好就行"。

💡 一句话：这套流程的价值在"门槛"，不在"产能"。 去掉门槛，建议会变成噪音，技能库会更快地烂掉。

三条铁律

1. 只建议，不动手 —— AI 出清单，人确认或忽略。创建、修改、淘汰都由人拍板后另走流程。
2. 建议必须指认信号 —— 每条建议写明命中哪条行为信号（见第 2 步）。指认不出来的不写进清单。
3. 被忽略的也要留痕 —— 记一句"为什么不要"，否则同一条件建议下次再来一遍，变成噪音。

第 0 步：定范围（别猜）

只问一个问题：这次是单技能体检，还是全库扫一遍？

别问"你想改哪部分""要不要加评测"——这些由流程判据决定，不是用户的选择题。

第 1 步：取证（只读，零写）

核心证据源是本地会话转写——不是技能文件本身。

理由：技能"该建没建 / 该改没改"，答案都在过去的会话里。 用户在哪件事上重复解释过、在哪句话上纠偏过、点名了哪个技能却没被触发—— 这些是行为留下的痕迹，比任何自评都可靠。技能文件只能告诉你"它长什么样"，会话才能告诉你"它有没有起作用"。

1.1 会话转写在哪

Claude Code 把每次会话逐条记成 JSONL（一行一个事件）：

${SKILLS_DIR}/projects/<项目路径转义>/<会话 id>.jsonl

# 先按时间收敛——只取最近 7 天有更新的会话，别全量扫
find ${SKILLS_DIR}/projects -name '*.jsonl' -mtime -7

# 单个文件可能几十 MB —— **取样，别通读**
tail -300 <会话>.jsonl
grep -n '不对\|不是这个\|又忘了\|应该用' <会话>.jsonl | tail -20

⚠️ 两点纪律： ① 取样 + 关键词过滤，不是通读；原始 JSONL 直接读可读性差，重点在筛。 ② 各工具的会话位置不统一（Codex 等在别处，路径以本机实际为准）—— 找不到就跳过并注明"未取到"，绝不编造会话内容。

1.2 从会话里提取三类信号

1.3 技能侧的取证

# 本机所有技能目录（按实际存在的路径取）
for d in ${SKILLS_DIR}/skills ~/.agents/skills ~/.codex/skills; do
  [ -d "$d" ] && find "$d" -maxdepth 2 -name SKILL.md
done

# 体积 / 行数（单文件超 16KB 或正文超 500 行是信号）
wc -l <各技能>/SKILL.md

再加上外部事实是否过期（版本号、支持周期、链接、许可）——这类必须能指认核实日期。

⚠️ 取证阶段全程只读。先看，别改。

第 2 步：归类（信号 → 建议类型）

每个发现必须归到下面三类建议之一，且能指认命中的信号。归不进去的不写进清单（防"感觉该建"）：

A. 建议新建（该建的没建）

B. 建议升级（该改的没改）

C. 建议淘汰（占着位子没用）

⚠️ 长期零调用的边界（不可越）：自动触发 ≠ 显式调用，低频 ≠ 无用。 零调用只能进观察名单，绝不可单独作为关闭依据。判"死"要人看内容后拍。

第 3 步：出清单（占决策带宽最少）

• 每批 ≤2 条，A/B 选择题，各带默认值与一句话权衡，推荐项标理由；
• 第 3 条起砍掉留到下批；禁开放式提问；
• 排序按「做了收益最大」，不按严重度堆砌；没命中的技能不列（不刷存在感）；
• 单次建议总量设上限（宁缺毋滥）——低于阈值的直接丢弃，不要攒着凑数。

清单长这样：

类型  | 对象        | 依据（信号）        | 建议动作           | 成本
建议新建 | （新的）     | 同类动作重复 4 次   | 固化为技能          | 中
建议升级 | xxx 技能    | 触发失败 ×3         | 改 description      | 低
建议淘汰 | yyy 技能    | 半年零引用 + 内容过期 | 退役或沉降          | 低

第 4 步：人确认 / 忽略

• 确认 → 进入对应流程：新建走创建流程；升级走第 5 步；淘汰由人决定去留后执行；
• 忽略 → 记一句为什么忽略（"这个用不着" / "已经有别的办法了" / "现在忙，先记着"）， 否则同一条件建议下次还会冒出来，消耗注意力；
• 一批处理完再出下一批。

第 5 步：升级类建议的落地（确认后）

1. 先备份：改前快照（cp 成 *.bak-YYYYMMDD 或走本区备份脚本）；
2. patch 实体：直接改 SKILL.md / 脚本，不建 -v2 目录副本（副本会造成同名双份， 下一个人分不清哪个是真的）；

3. 改动前先有评测（最小定义：一个能失败的检查，不是测试框架）：

   改什么	最小评测长什么样
   description（触发面）	列 3~5 句用户真会说的话 → 逐句判断改前/改后是否触发（写下来，别在脑子里过）
   步骤 / 判据	一个最小复现脚本：按新步骤跑一遍，断言预期输出
   单纯文案/排版	不需要评测（不影响行为）

   评测必须能被别人重跑：命令 + 预期输出写进提案，不写"我试过了"。

4. 跑评测确认没退化；退化了就回滚；
5. 登记：改了哪个文件、为什么、依据哪条信号。

排错

红线

• ❌ 不自行创建技能、不自行改技能 —— 只出建议，人确认或忽略；
• ❌ 不用"用户说了某句话"当触发判据 —— 只看行为信号；
• ❌ 不建议无依据的改动 —— 说不出命中哪条信号的，不进清单；
• ❌ 不建 -v2 副本 —— 升级就是 patch 实体；
• ❌ 长期零调用不自动判死 —— 只进观察名单，人看内容后拍；
• ❌ 不追加"每会话都出建议" —— 触发太频繁 = 噪音，按需或定期跑；
• ✅ 建议落地后当场验证：说一句触发词，看技能起不起。

原 description（存档，不注入上下文）

技能建议 / 技能体检 / 要不要做成技能 / 这个该沉淀成技能吗 / 技能该升级了 / 技能老化了 / 技能没人用 / 技能触发不了 / 技能该淘汰 / 库太肥了要淘 / skill hygiene / skill evolution —— 在干活的过程中主动产出技能建议：① 建议新建（某类动作反复出现，还没技能承载） ② 建议升级（已有技能触发不了 / 踩过同一个坑 / 内容过期）③ 建议淘汰。 每条建议都由人确认或忽略，AI 不自行创建、不自行改动。 触发看行为信号（重复 / 纠偏第二次 / 零调用 / 内容过期 / 池超容），不看"用户今天说了句什么话"。