Skill 问题诊断

先找出问题出在 description、入口路由、单份文档，还是多份文档配合，再修改对应位置。不要看到一次结果不好，就把所有文件重写一遍。

排查顺序

1. 还原问题：保存原始请求、实际输出和读取记录，指出具体哪一步不符合预期。
2. 确认是否进入 Skill：没进入时先检查可发现性，再排查 description。
3. 确认是否找到所需资料：进入了但找错或漏读文件，排查路由。
4. 确认单份资料能否指导执行：读对文件仍做错，检查该文件的规则和做法是否清楚。
5. 确认组合后有没有问题：单独可用、一起失效时，检查冲突、顺序、信息交接和读取负担。
6. 修改并复测：改有证据支持的位置，再用原任务和相关正常任务观察影响。

已有明确证据时从对应步骤开始。用户直接指出措辞或结构问题时可以直接修改，不必强制跑完整套诊断。

1. 还原问题

先写下这几项，再决定改哪里：

原始请求及必要材料：
期望得到什么：
实际哪里不符合要求：
实际使用的 Skill 版本：
读取了哪些文件、顺序怎样：
相关回答、文件或调用记录的位置：

• 找不到读取记录时写“未知”，不要把“没有看见”写成“没有读取”。
• 文件打不开、工具被拒绝、版本没有更新时，先处理环境问题。
• 需要复现或比较时，按测试与迭代准备独立会话、相同输入和验收依据。

2. 没进入 Skill：排查 description

先看：Skill 是否在当前环境可被发现，以及原请求是否属于它的能力范围。

怎么排查：

1. 在正常可用的环境中用原始请求运行，记录是否选择了 Skill。
2. 在新会话中用相同任务，明确要求使用该 Skill。
3. 对照两次结果；必要时换一条同意图、不同说法的请求再次观察。

观察结果	下一步
自然请求未选择，显式使用后能正常完成	优先检查 description 是否遗漏这类能力或场景，也检查其他 Skill 的竞争与上下文影响
显式指定仍无法读取	先查发现、路径、权限或运行时，不急着改 description
两种方式都使用了，但都做不好	转到路由和内容排查

显式使用成功只是缩小范围的证据，不足以单独证明 description 是唯一原因。确认描述有缺口后，按 Skill 入口模板 概括能力和场景，不把失败请求原句追加成触发词。

3. 进入了但读错资料：排查路由

先看：从原始任务出发，你期望读到哪份资料；实际读到了哪些。

怎么排查：

1. 对照 SKILL.md 索引，找出原请求应该对应的入口。
2. 检查索引是否说明了如何识别该类问题，链接是否可达。
3. 在新会话中明确指出应读取的参考文件，让执行者完成同一任务。
4. 比较正常路由与指定文件后的结果。

• 指定文件后改善：优先修索引的识别条件或资料间的阅读指引。
• 指定文件后仍失败：继续检查文件内容或执行环境。
• 正常任务同时需要多份资料：检查索引是否误导执行者只选一份，或没有说明必要的先后关系。

修改方式见 Skill 入口模板。仅仅增加文件链接不一定够，还要让当前问题能对应到该入口。

4. 读对文件仍做错：排查单份文档

先看：失败动作在文档中由哪段内容指导，或本应在哪里得到说明。

逐项检查	具体做法
要求有没有写清	找出对应句子；分清必须遵守、推荐和可选，检查是否有相反表述
读者是否知道怎么动手	对照实际任务，找出所需输入、具体动作和判断结果的依据；缺哪项就补哪项
重点是否被埋住	只看开头能否知道该完成什么，再找后文是否有对应展开
示例是否误导	对照示例和规则，检查示例是否暗中增加条件或改变原意

如果尚不清楚问题在哪，在测试副本中只改疑似段落，再完成相同任务。可以先用指定文件的方式观察局部效果，但最终仍需回到正常入口验证。

修改方式见 document-writing Skill 的文档写作原则；决定哪些要求应保留、应约束多细时看 信息取舍与约束程度。

5. 单独可用、一起失效：排查文档配合

先看：组合任务中哪些文件共同参与，每份文件负责什么、后一步需要前一步提供什么。

先把衔接写出来

文件 A 负责：
A 应提供的结果：
文件 B 负责：
B 需要的输入：
两份文件都对同一动作提出了哪些要求：

再对照实际读取和执行记录，检查：

可能的问题	怎么找到证据	对应修改
规则冲突	找出针对同一动作给出不同要求的具体句子	明确各自适用条件或统一规则，避免靠执行者猜优先级
阅读或执行顺序不对	后一步在前置结果形成前就开始执行	在实际衔接处说明前置条件和顺序
信息交接不完整	A 的结果缺少 B 必需的字段、材料或结论	写清 A 应输出什么、B 从哪里读取，不靠含糊的“继续处理”
职责重叠	两份文件重复要求同一动作，或重复修改同一产物	明确哪个文件负责，另一份引用其结果
无关内容干扰	正确资料已经读到，但加入其他资料后反复忽略关键要求	在测试副本中逐项减少无关材料，观察是否改善，再调整按需读取范围

用组合对照缩小范围

以下是诊断办法，不要求每次全部执行：

1. 让 A 完成它负责的子任务，保存实际结果。
2. 给 B 一份已确认满足输入要求的材料，检查它能否完成自己的子任务。
3. 把 A 的实际结果交给 B，观察差异。
4. 最后从正常入口完成整项任务，检查整条链路。

B 在第 2 步通过、第 3 步失败，优先检查交接；分步通过、整项任务失败，再检查路由、执行顺序和上下文影响。各次试验保持相关材料和条件可比，诊断副本也保留用户约束，不通过移除必要约束换取成功。

6. 修改并复测

• 写清改动理由：例如“实际未读到测试文档，索引缺少结果分析的识别条件，因此只改该入口”。
• 改动与原因对应：路由问题改入口，局部说明问题改对应段落，衔接问题改两份资料的接口约定。
• 回到正常路径：诊断时指定文件能成功，不代表正常使用已经改善；用原始请求从正常入口再试。
• 保留相关正常案例：确认修复没有破坏此前正确的行为；执行与评判方法见测试与迭代。
• 记录实际结论：保留哪些修改、证据是什么；没有改善就回看假设，证据不足就注明，不继续盲目加规则。

单纯文档编辑不自动启动上述试验。真实问题按 document-writing Skill 的文档写作原则沉淀；发布和同步另按用户要求处理。