skill-load-tips

Skill 加载提示

适用于以下 SKILL.md 文件的重构模式：Agent 唯一会读取的内容就是正文。references/ 文件夹可能根本就不该存在。

失效模式

大型技能通常会附带丰富的参考文件（references/*.md），其中包含关键细节——完整的 ARIA 模式、禁用词列表、前后对照示例、原型分类——而 SKILL.md 正文则只是对这些内容的概述。Agent 读完正文，觉得自己已经“了解得够多”，便不再深入查阅。参考文件就此成了摆设。

这就是内联内容替代参考文件的反模式。这是结构良好的技能表现不佳最常见的原因。

症状（如何识别）

如果以下情况中有两项或更多符合，SKILL.md 很可能就存在这个问题：

• 正文超过 250 行，且内嵌了清单、表格或禁用词列表，而这些内容也存在于引用的文件中。
• “Reference Index” / “Files” 部分放在底部，位于操作流程之后。
• 引入参考文件时使用了含糊的措辞：“想深入了解，请阅读 X”、“详情见 X”、“X 中有更多内容”。
• 没有提前提供“路由表”，将任务映射到必读文件。
• 参考文件相互链接，形成深层嵌套，而不是由 SKILL.md 直接链接。
• 超过 100 行的参考文件顶部没有目录。

四项修复措施（按顺序应用）

修复 1 — 在顶部添加必读路由表

在技能的开篇段落之后立即插入一张表格（位于任何“操作流程”/“步骤”章节之前）。该表格将任务类型映射到该任务必须阅读的文件。

模板：

## Required Reading Router

Match your task to the row. Read the listed files **in full before** producing output. They are not appendices — they are load-bearing. Inline content in this SKILL.md is a pointer, not a substitute.

| Task                                          | MUST read                                                    |
| --------------------------------------------- | ------------------------------------------------------------ |
| [Task type A]                                 | `references/file-a.md`                                       |
| [Task type B]                                 | `references/file-b.md` + `references/file-c.md`              |
| [Task type C]                                 | `references/file-d.md`                                       |

在路由表下方紧接着放置参考索引：用一行描述每个文件的内容。这样，路由表告诉 Agent何时加载，索引则告诉 Agent能获得什么。

修复 2 — 在操作步骤中使用强制 STOP 指令

每个有对应参考文件的步骤，都要在末尾添加强制阅读指令。将委婉措辞改为祈使句。

之前：

For ARIA component patterns and verification recipes, read `references/accessibility-floor.md`.

之后：

**STOP. Read `references/accessibility-floor.md` in full before implementing or reviewing any interactive widget.** That file contains the complete ARIA patterns (dialog, combobox, menu, tabs, slider, listbox) and the verification recipes. The inline summary above is a tripwire, not the contract.

STOP 指令的三条规则：

1. 将 STOP 一词加粗。这是一个视觉上的中断提示。
2. 写明触发条件（“实现交互式小部件时”“扩展 tokens 时”）。不能只写“如果你想深入了解”。
3. 说明内联内容只是触发提醒，并非权威依据。

修复 3 — 将重复的内联内容精简为要点提醒

如果 SKILL.md 的某个步骤包含一份 10 条要点的清单，而参考文件中也有相同内容，Agent 读完清单就会跳过参考文件。将内联内容压缩为 2–3 行的“触发提醒”——足以让 Agent 扫读时发现违规，但显然并不完整。

之前（内联的 10 条 WCAG 检查清单）：

- Text contrast ≥ 4.5:1 (≥ 3:1 for large text)
- Non-text indicators contrast ≥ 3:1
- Focus visible (2px minimum)
- Keyboard reachable
- Target size ≥ 24×24
- prefers-reduced-motion honored
- Semantic landmarks
- Headings in order
- Form controls labeled
- Errors associated via aria-describedby

之后（3 行提醒 + 强制阅读）：

Gist tripwires — the floor items that catch most slop:

- Text contrast ≥ 4.5:1; focus-visible ≥ 2px on every interactive element.
- Full keyboard reachability; `prefers-reduced-motion` honored.
- Semantic landmarks + heading order; form controls programmatically labeled.

**STOP. Read `references/accessibility-floor.md` in full before implementing or reviewing any interactive widget.** The three bullets above are tripwires, not the contract.

要大幅精简。如果内联列表和参考文件涵盖相同内容，始终以参考文件为准。

修复 4 — 将参考文件层级扁平化为一层

根据 Anthropic 的文档：参考文件相互链接时，Agent 会使用部分读取（head -100），从而遗漏内容。所有 references/*.md 文件都必须由 SKILL.md 直接链接，而不是相互链接。

错误示例：

SKILL.md → references/advanced.md → references/details.md

正确示例：

SKILL.md → references/advanced.md
SKILL.md → references/details.md

此外：任何超过 100 行的参考文件都需要在顶部添加 ## Contents 章节，以便部分读取时仍能显示其涵盖范围。

反模式

看似有效、实则无效的做法：

• 在现有触发语句中添加“（重要）”或表情符号。 Agent 会读取语气，而不是装饰。强制性措辞需要使用动词（STOP. Read…），而不是形容词。
• 缩短参考文件，让正文可以继续内嵌。 这与目标背道而驰。正文越短，参考文件就应该越长。
• 在每个参考文件顶部添加“TL;DR”。 Agent 读完 TL;DR 就会跳过正文。请改用目录 TOC——列出章节名称，而不是摘要。
• 通过重命名参考文件来暗示紧急程度（URGENT-read-this.md、MUST-READ.md）。文件名不会改变读取决策；SKILL.md 中的触发措辞才会。
• 将 SKILL.md 拆成多个同级的小文件。 SKILL.md 是唯一入口。多个顶层技能文件会破坏发现机制。

重构检查清单

宣布重构完成前，请根据改写后的 SKILL.md 逐项核对：

• 前 50 行中存在必读路由器（简介/理念之后）。
• 参考索引紧邻路由器。
• 每个有对应参考文件的操作步骤，结尾都有 **STOP. Read references/X.md …** 指令。
• 与参考内容重复的内嵌检查清单已精简至 ≤ 3 条，并标注为“易错点”或“概要”。
• 没有任何参考文件链接到另一个参考文件（仅允许一层）。
• 超过 100 行的参考文件顶部有 ## Contents TOC。
• SKILL.md 正文少于 500 行（Anthropic 建议的上限）。
• 不再保留 For depth, see X 或 Read X for more 这类措辞——每处参考文件提及都必须是路由器/索引（说明性）或 STOP 指令（强制性）。

如何执行一轮重构

1. 并排打开 SKILL.md 和 references/ 目录。
2. 清点：列出每个参考文件及其涵盖内容。
3. 诊断：逐项检查上方的症状列表，并标记命中的项目。
4. 按顺序应用修复 1（路由器 + 索引）、修复 2（STOP 指令）、修复 3（精简内嵌内容），再应用修复 4（扁平化层级 + 添加目录）。
5. 运行检查清单。如有任何项目未勾选，重构就尚未完成。
6. 通过让一个全新的 Agent 实例执行需要参考文件的任务来测试。观察它是否确实读取了文件。如果没有，则该文件的 STOP 指令力度不足——请加强触发条件。

何时不应使用

• 从头开始编写新技能——请使用 skill-best-practices。
• 仅编辑参考文件，不改动 SKILL.md。
• 少于 150 行且没有参考文件的技能（无需路由）。
• AGENTS.md / CLAUDE.md 重构——它们遵循不同规则；请使用 agent-md-refactor。

总结

A reference file the agent never loads is a reference file that does not exist.
The body of SKILL.md is a dispatcher, not an encyclopedia.
Trim the inline. Force the load. Flatten the depth.