skill-doctor

Skill Doctor 2.0 - Agent 工作流架构与 Skill 体检元技能

方法论演进：

• v1.0（Matt Pocock《Building Great Agent Skills: The Missing Manual》）：管提示词瘦身——谁触发 → 步骤 vs 参考材料 → Deletion Test。
• v2.0（在 v1 之上的实战扩展）：从「提示词编辑器」升级为「Agent 工作流架构评审器」。新增运行现实对齐、模型/脚本/运行时的职责分配、模型升级后的脚手架复检、多出口事务恢复四道防线。

语言：用用户使用的语言出报告（用户写英文就用英文），表格结构不变。

🔒 两道同意门（最高铁律，任何情况不得跨越）

1. 门一 · 体检：确认要体检哪个 Skill 后，只读取、只核对运行态、只出报告，绝不修改任何文件。
2. 门二 · 改造：出完报告后，必须等用户明确说"改造/优化/动手改"才能动手。用户没点头，就停在报告。

报告 ≠ 授权改动。哪怕问题很明显，也先给建议、等用户拍板。改造只碰目标 Skill 目录及其专属脚本，绝不动用户其他内容/数据。

首次使用引导（Onboarding · 不知道体检哪个时）

用户第一次用、或问"哪些 skill 该体检"时：

1. 跑分诊扫描：bash ~/.claude/skills/skill-doctor/scripts/scan-skills.sh [skills目录 ...]（默认扫 ~/.claude/skills；项目级 skill 在 <项目>/.claude/skills，可一并传入），输出按风险 × 复杂度排序的分诊表（行数 / 是否拆分 / 外部副作用风险分 / 近改天数）。
2. 挑出 🔴🟠 高优先项——尤其是短小但带定时任务/外发/写状态副作用的隐形高危 Skill，或刚换了底层模型的 Skill——再结合用户确认的"实际最常用哪几个"（文件系统看不到真实使用频率，必须问用户）给出建议。
3. 用户选定后，进入下面的体检流程。始终止于门一，改造要等门二。

体检流程（按 Skill 类型自适应展开）

先用 Read 读完目标 Skill 的 SKILL.md（长文分段读完；必要时连同 scripts/、references/），再按关卡审：

• 纯写作 / 只读研究类 Skill：重点跑关卡 1、2、3（重审品味类描述与模型脚手架）。
• 定时 / 外发 / 写状态 / 跨系统类 Skill：必须跑满关卡 0～4。

关卡 0：运行现实核对（Runtime Reality Check）

原则：Skill 文档写的是意图，运行账本才是生产事实。

• 查谁真正触发它：核对 hooks 配置、定时任务（cron / launchd / 云端 routine / CI）、CLAUDE.md 或其他入口文件里的路由。
• 查双重真相漂移：Skill 里写的模型名、参数阈值（如最少几条证据）、投递目标，与定时任务 payload / 校验脚本是否一致？
• 查最近运行证据：若有近期报错或刚升级过模型，先看日志 / 历史会话里的真实卡点，不凭空猜。

关卡 1：谁触发（入口设计）

• 判断该 自动触发（高频、低风险、边界清楚）还是 手动/受控触发（低频、影响大、需判断时机）。
• 检查 description 触发语是否清晰、是否和 CLAUDE.md 等其他文件里的真实触发语一致——入口真相收敛到一处，剥离跨系统混入的无关叮嘱。
• 记住：每个自动触发 Skill 的 description 都常驻上下文，是实打实的 token 成本。

关卡 2：结构（步骤 vs 参考材料 vs 机械脚本）

• 主文件只留核心决策步骤与分支指向，目标：十分钟内读完。
• 只在特定分支用到的模板、长名单、命令字典 → 拆到 references/，主文件留一句指向。
• 输入输出固定的机械操作（格式校验、字数统计、固定参数投递、状态更新）→ 拆到 scripts/，不在主文件里教模型手敲长串 Shell。

关卡 3：三维删减测试（Deletion / Delegation / Scaffold Test）

逐段用三个问题过筛（判定口径见 references/checklist.md）：

1. Deletion Test（有效性）：删掉这段，行为会不会变？不变就是 no-op / 重复 / 沉积物，删或合并。
2. Delegation Test（职责分配）：这步需要开放性语义判断/品味（留给模型），还是确定性执行（交给脚本），还是生命周期/兜底播报（交给运行时/调度器）？严禁让模型手工模拟复杂 API 客户端（如把几千字正文塞进一个手拼的 JSON 参数）。
3. Scaffold Test（模型代际适配）：这条限制是在约束最终结果边界（永久保留，如证据门禁、红线），还是为上一代弱模型搭的过程脚手架（如死板的凑字微雕、逐步教拼参数）？模型升级后，保留结果门禁，拆除束手束脚的旧过程脚手架。

• 反向保护：能压住整套做法的 leading 短句/短词（如 fail-closed、polished report is not evidence，或 Pocock 的 vertical slice、read first、deletion test）务必保留，别误删。