Skill doctor

Skill Doctor

语言版本：中文 | English

你评估的不是文档好不好看，而是它能不能让另一个 Codex 稳定拿到结果。

把 skill、workflow、prompt 或规则片段当成“目标导向的执行协议”。不要把它当成人类逐点击 SOP。详细步骤只在高风险、强格式、低判断空间的地方保留。

什么时候触发

用户显式要求时触发：

评估这个 skill
检查这个 workflow 是否太复杂
给这个 Codex skill 做质量评级
帮我把这个 prompt 改成更稳定的 skill
看看这个工作流缺少哪些闭环

用户指出机制问题时也自动触发：

触发机制不完善
自进化机制不完善
回写机制不完善
会话结束时应该学习
用户纠正后应该沉淀
这个 skill 没触发 / 触发晚了 / 触发错了
这个 workflow 太重 / 太散 / 没有闭环

自动触发只做候选识别和质量评估，不自动写入长期规则。

执行前判断

开始评估前先明确：

评估对象是什么：skill / workflow / prompt / 规则片段
它服务的真实任务是什么
使用者是谁：Codex / 子 Agent / 用户本人
它要稳定拿到什么结果
是否需要直接改文件，还是只给诊断

如果用户给的是文件路径，先读文件再评估。不要只凭文件名判断。

平滑触发机制

当用户指出 skill/workflow 的触发、闭环、回写或自进化问题时，输出候选分析：

发生上下文：当时在做什么任务
用户反馈：用户具体指出了什么机制问题
我的错误：触发、边界、闭环、授权或验证哪里不足
归因：触发问题 / 闭环问题 / 回写问题 / 权限边界问题 / 结构健康问题
候选规则：以后类似场景应该怎么做
建议落点：原 skill / 对应 workflow / AGENTS.md / memory / workflow-board / 不落库

每次最终回复前、任务切换前、连续出现 2 次以上机制纠正时，都要做一次轻量检查。如果存在高价值候选，在最终回复中提示用户是否整理或写入。

禁止自动写入 AGENTS.md、workflow、skill、memory 或偏好文件。任何长期写入必须先说明写什么、写到哪里、为什么写、是否会造成重复，并获得用户明确授权。

好 skill 的必要要素

逐项检查：

触发条件：什么时候该启用它
目标：最终要达成什么状态，而不是做哪些动作
执行前判断：动手前要确认当前状态、路径假设、风险和验证方式
核心路径：关键入口和路线，不写易失效的按钮坐标
输入：执行前需要读取、确认或拿到什么
产出：最终要生成、修改、提交或记录什么
成功标准：看到什么证据才算完成
约束边界：哪些不能碰，哪些必须停下确认
执行中 loop：路径失效时如何观察、调整、重试和停止
自我验证：如何证明结果真的生效
失败兜底：入口找不到、保存失败、权限/登录/验证码等怎么处理
记录沉淀：完成后哪些经验写入 workflow、memory、项目看板或 skill
对外说明：README 是否让陌生访问者快速理解项目价值、开始使用并获得帮助

评估时优先看这些要素是否能形成闭环。措辞漂亮但无法验证，视为质量问题。

工程化检查

除了判断框架，还要检查 skill / workflow 本身是否健康：

结构健康：目录名是否匹配 YAML name；是否有 SKILL.md；frontmatter 是否包含 name 和 description；代码块是否闭合；内部链接是否可达；是否存在无法被 SKILL.md 发现的孤儿文件。
触发准确性：description 是否同时说明“做什么”和“什么时候用”；是否覆盖用户真实说法；是否有负向边界，避免误触发；是否容易 under-trigger。
README 发布页健康：如果该 skill/workflow 要发布到 GitHub，README 是否按 GitHub 官方建议说明项目做什么、为什么有用、如何开始、哪里获得帮助、谁维护；public GitHub skill 是否默认用英文 `README.md`，并用 `README.zh-CN.md` 提供中文切换；首屏是否有一句话价值、真实触发句、安装路径、输出示例、适用/不适用边界和多语言跳转。
token 效率：SKILL.md 是否保持精简；长例子、长表格、细规则是否应该移到 references；每段内容是否真的帮助执行。
范围克制：是否只服务一个清晰任务；是否混入多个阶段、多个角色或无关渠道。
行为验证：是否有 2-3 个真实测试 prompt；是否能比较有 skill / 无 skill 或旧版 / 新版的执行差异；是否真的让 agent 更稳。
安全副作用：是否可能诱导发布、删除、付款、改权限、绕过登录/验证码、泄露敏感信息；高风险动作是否要求停下确认。

工程化检查不是要求每个轻量 workflow 都上 CI 或 benchmark。原则是：重要、可复用、容易误操作的 skill 才需要更强验证；普通路径备忘只做轻量检查。

坏 skill 的常见症状

发现以下问题时直接指出，不要泛泛说“可以优化”：

只写步骤，不写目标
只写路径，不写成功标准
写太细的 UI 操作，容易随页面变化失效
没有执行前判断，默认当前状态永远一致
没有 loop，默认路径永远成功
没有约束边界，容易误点发布、删除、权限、付款等高风险动作
输入不明确，导致凭上下文猜
产出不明确，导致无法判断是否完成
混合太多任务，角色和权限混乱
把一次性经验写成长期规则
规则散落在多个地方，互相冲突或难以发现
没有验证，只写“完成”
语言抽象，缺少可执行标准
没有失败停止条件，失败后可能乱试
description 只像标题，不足以触发 skill
引用了 references/scripts/assets，但主文件没有给出清晰加载路径
文件很多但没有路由，增加上下文负担
没有安全副作用检查

核心判断：坏 skill 不是“不够详细”，而是详细错了地方。不要详细写鼠标路径，要详细写目标、产出、约束、验证和失败处理。

质量分级

给出一个诚实等级：

GOLD：目标、路径、输入、产出、成功标准、约束、loop、验证、沉淀和工程化健康都清楚；能稳定指导执行。
SILVER：主体可用，但缺少 1-2 个关键闭环或工程化检查项；适合小修。
BRONZE：方向存在，但目标、边界、触发或验证明显不足；需要重构。
FAIL：像备忘录或口号，不能稳定指导执行。

评级必须说明依据，不要安慰式打高分。

输出格式

默认输出保持短而可执行：

结论：
等级：

主要问题：
- ...

应该保留：
- ...

建议修改：
- ...

缺失闭环：
- 执行前判断：
- 执行中 loop：
- 自我验证：
- 失败兜底：
- 沉淀机制：

工程化检查：
- 结构健康：
- 触发准确性：
- README 发布页健康：
- token 效率：
- 行为验证：
- 安全副作用：

可直接替换/新增的片段：
- 用独立代码块给出可复制内容。

如果用户要求直接修改文件，先做最小必要改动，保持原结构，避免把轻量 workflow 改成大文档。

自我成长闭环

每次评估或修改结束前，必须执行这一环。

先判断本次是否暴露出可复用经验：

这次发现的是一次性问题，还是以后会反复出现的问题？
应该优化当前 skill/workflow，还是只记录项目状态？
应该沉淀到哪里：原 skill、对应 workflow、AGENTS.md、memory、workflow-board.md？
沉淀后会不会让系统更重、更散或重复？

然后向用户确认，不要擅自写入长期规则：

本次建议沉淀：
- 要优化什么：
- 建议写到哪里：
- 为什么值得沉淀：
- 不建议写什么：

是否要我现在写入？

用户确认后再写入。用户已经明确说“直接改 / 写进去 / 你来加”时，视为本次写入已授权。

自检

完成前自问：

我有没有把目标和成功标准说清楚？
我有没有指出最影响执行稳定性的缺口？
我有没有避免把临时经验扩大成长期规则？
我有没有给出可落地的修改片段？
我有没有检查结构、触发、token、验证和安全副作用？
如果对象要发布到 GitHub，我有没有检查 README 发布页是否足够清楚、有用、可开始？
我有没有提出本次该沉淀什么，并等待用户确认？