Skill 自检与整改助手（skill-repair）
让一个 Skill 能够自己发现问题、修复自己、再验证自己——形成"体检 → 诊断 → 整改 → 复检"的闭环。本 Skill 既可用于整改其他 Skill，也可对本 Skill 目录（skill-repair/ 自身）执行同样的流程，实现"自我整改"。
整改的权威依据来自 SkillHub TRACE 评测体系：Trust（可信任度）、Reliability（可靠性）、Adaptability（适用性）、Convention（规范性）、Effectiveness（有效性）五个维度。每个问题都要落到具体维度、具体子项，避免"泛泛优化"。
何时触发
满足以下任一情形即应触发：
- 用户说"检查/体检/评测这个 Skill""帮我整改/修复/完善 Skill""TRACE 分低了，帮我提升""README/SKILL.md 不规范"。
- 用户提供了 TRACE 评测报告（如本次附带的报告），希望据此整改。
- Skill 出现典型症状：核心功能只有模拟/占位数据、报错是一堆英文堆栈、缺 FAQ 与反模式、触发词没有示例、目录结构混乱。
- 用户要新建一个 Skill：先按本 Skill 的"规范基线"搭骨架，再填充能力。
不触发：修复与 Skill 无关的普通业务代码、数据脚本、非 Skill 项目。
整改核心流程
整改前先确定目标 Skill 的根目录（被整改对象）。若用户未指明，用 ask_user_question 询问一次；默认即当前工作区中除本 Skill 外的目标目录。整改对象绝不可与本 Skill 目录混淆——除非用户明确说"修复 skill-repair 自己"。
第 1 步 · 建立基线（扫描）
只做只读扫描，不动任何文件：
- 确认目录结构符合"规范基线"（见
references/spec-baseline.md）：是否存在SKILL.md、frontmatter（name/description）、references/、scripts/、assets/；文件命名是否清晰。 - 通读
SKILL.md：frontmatter 完整性、正文是否有"执行流程 / 工具规则 / 运行约束 / 完成条件"等必备章节。 - 检查 TRACE 五维度证据：逐项对照
references/trace-criteria.md，记录每条子项的达标情况与证据（引用具体文件/行号）。 - 识别典型坏味道（详见第 3 步的问题分类表）。
扫描结果写成一份基线报告（在脑内或写入工作区 baseline.md），每条问题带：[维度.子项] 问题描述 · 证据位置 · 严重度(P0/P1/P2) · 建议动作。先呈现基线给用户确认，再动手修改——避免误改。
第 2 步 · 与用户确认整改范围
基线出来后，默认通过 1 次 ask_user_question 让用户选择整改重点（对应 TRACE 失分项）。推荐选项固定为前 3~4 个 P0/P1 问题 + "全部整改"。示例：
- 问："以下是最突出的问题，先重点整改哪些？"
- A（推荐）：补齐异常处理与 FAQ/反模式（R 异常、C 反模式）
- B：替换模拟占位逻辑为真实可用实现（E 输出准确性）
- C：补全触发词示例与能力边界说明（A 适用性）
- D：全部整改
用户选"全部整改"或超时即按全部处理。这一步不要反复追问，最多 1 次。
第 3 步 · 执行整改（按问题分类）
下面是本报告评测出的真实问题与各维度通用修复模式。遇到具体问题时查表选用，不要每题都硬套。
| 问题类别（TRACE 失分项） | 典型症状 | 整改动作 | 落点文件 |
|---|---|---|---|
| R·异常处理弱 | 出错只抛英文堆栈，用户不知如何修复 | 加统一错误处理：捕获异常 → 输出中文诊断（是什么、为什么、怎么修）→ 提供回退/重试；在文档列常见报错与解法 | scripts/ 工具函数、SKILL.md 运行约束 |
| E·模拟/占位 | 核心功能返回 mock 数据，无法真正产出 | 抽象出可插拔的 Provider 接口（如 LLM/数据源），默认提供真实实现骨架 + 清晰的接入指引；保留 mock 仅作离线演示 |
scripts/providers/、配置说明 |
| C·反模式/FAQ 缺失 | 几乎无 FAQ，接入方式、常见报错无处查 | 新增 references/faq.md 与"反模式"清单；每条 FAQ = 问题 + 原因 + 步骤 + 代码块 |
references/faq.md |
| A·触发/边界不清 | 触发靠关键词但无示例，能力边界分散 | 在 SKILL.md 补"何时触发/不触发"清单 + 触发示例对话；能力边界集中在一处声明 |
SKILL.md 顶部 |
| C·结构/渐进披露 | 文档无分层指引，新手无从下手 | 采用"快速参考 → 执行流程 → 详细规则"三层；目录图 + 每文件职责说明 | SKILL.md、references/ |
| T·安全/可信 | 外部调用无校验、敏感信息硬编码 | 加输入校验、敏感配置走环境变量、依赖清单锁定版本；高危操作先确认 | scripts/、config |
整改硬规则：
- 一次只改一个关注点，改完即验证；不要一次性大改所有文件再统一看结果。
- 改
SKILL.md前先read全文，确保edit的old_string精确匹配；优先用edit，只有整体重写才write。 - 新增/修改脚本后必须实际运行验证（如
python3 scripts/xxx.py），不能只改不跑。 - 保留向后兼容：删除或重命名前确认无其他文件引用；配置项提供默认值与说明。
- 不要编造无法验证的事实（如"已对接某模型"）——真实接入才写真实，否则明确标为"待接入"并在 FAQ 给出步骤。
第 4 步 · 回跑验证（复检）
整改后必须复检，形成闭环：
- 结构校验：目录、
SKILL.mdfrontmatter、必备章节是否齐全——可运行python3 scripts/check_skill.py <目标目录>（本 Skill 自带，见下）。 - 功能冒烟：目标 Skill 的脚本逐个跑通；本 Skill 的整改脚本至少自测一次。
- TRACE 重评：用
references/trace-criteria.md逐项重新打分，与基线对比，确认失分项已改善。 - 输出整改报告：列出
问题 → 改动文件 → 验证结果 → 剩余风险。
若复检不通过，只针对失败项再改一轮即停；不要无限循环修复。
第 5 步 · 交付
向用户说明：整改了什么、改了哪些文件、验证了什么、还剩哪些（若有）。不主动打包为 zip；若产物文件 ≥ 5 个或为整个目录，再打包。
工具规则
read/write/edit：整改的主工具。write用于新建文件，edit用于精准修改已有文件，改前必先read。bash：运行目标 Skill 的脚本与本校验脚本做验证。只在目标 Skill 目录或其子目录内执行，不写破坏性的递归删除。ask_user_question：仅在第 2 步（确认整改范围）调用，最多 1 次、最多 4 题。web_search/web_fetch：仅当整改涉及外部规范（如某平台官方 API、最新 SDK 用法）且本地无依据时使用；纯内部结构问题不联网。- 本 Skill 自带的
scripts/check_skill.py：对目标目录做静态结构校验，是复检的核心工具，详见scripts/README.md。
运行约束
- 整改对象默认是用户指定的 Skill 目录；唯有用户明确要求时才整改本 Skill（
skill-repair/）自身。 - 只读阶段（第 1 步）绝不修改文件；确认阶段（第 2 步）完成前不写代码。
- 不虚构评测分数、不声称"已通过 TRACE 5.0"——所有评分须有逐项证据。
- 对无法自动修复的项（如需真实 API Key、需人工决策的能力边界），明确列为"待人工"，在 FAQ 给出操作步骤，不假装已解决。
- 不读取未来执行状态，不维护跨会话的记忆/进度文件。
完成条件
- 基线报告已产出（或已口头呈现关键项并获确认）。
- 整改项已落到具体文件改动，且改动后的脚本实际运行通过。
- 复检（结构校验 + TRACE 重评）已完成，整改报告已交付。
- 若因权限/依赖无法运行某项验证，如实说明，不伪造通过结果。
