本节对应 Gotchas sections，只解决一种问题：Agent 按一般经验完成了操作，却漏掉本项目里的具体例外。
问题
Agent 可能作出在一般项目里合理、但不适用于当前环境的判断：认为查出的用户记录都是有效账号，认为不同系统使用相同的用户 ID 字段名，或者认为健康检查返回 200 就说明整个服务已经就绪。
仅写“认真检查”“注意边界情况”，没有交代缺的是什么，也没有说明怎么补齐。
解决方案
将易错点写成三件事：在哪种情况下发生、实际规则是什么、应该采取什么行动。
重点是写出当前环境中会打破这些假设的具体事实，并说明因此应该怎样操作。
这类不明显的例外适合放在 SKILL.md 中，让 Agent 在遇到它之前就能读到。若只写“遇到未跟踪文件遗漏时再读参考资料”，Agent 可能根本意识不到已经遗漏。
最小示例
官网原例：三个环境特有的易错点
以下是官网 Gotchas 原例的中文译文，保留表名、字段名、查询条件与接口路径。这是 SKILL.md 正文中的一个片段：
## 易错点
- `users` 表使用软删除。查询必须包含 `WHERE deleted_at IS NULL`，
否则结果会包含已停用的账号。
- 用户 ID 在数据库中叫 `user_id`，在身份认证服务中叫 `uid`，
在计费 API 中叫 `accountId`。三者指向同一个值。
- 只要 Web 服务器正在运行，`/health` 就会返回 200，
即使数据库连接已经断开。使用 `/ready` 检查完整的服务健康状态。
这三条分别补上不同的知识缺口：
| 可能作出的假设 | 这个环境中的实际约定 | 因而需要改变的做法 |
|---|---|---|
| 查出的用户记录都是有效账号 | 用户采用软删除 | 查询排除已停用的账号 |
| 同一个用户 ID 在各系统里字段同名 | 三个系统的字段名不同 | 按明确的对应关系读取和传递 |
/health 返回 200 就表示所有依赖正常 | 这个接口只表明 Web 服务器正在运行 | 用 /ready 判断完整就绪状态 |
这些是官网示例项目中的设定，使用到自己的项目时需要核对事实。原文还建议：当一次执行出现了需要纠正的错误，把可复用的纠正补进易错点部分。
迁移练习：写出自己项目中的同类提醒
本站的 Git 例子用于练习上述方法。用户要求审查当前未提交改动时，git diff HEAD 不包含未跟踪文件的正文；需要先列出这些文件，再根据范围读取相关内容。
下面是根据本站 review-diff 练习裁剪的完整教学文件，只保留改动检查和这一条易错点：
---
name: review-diff
description: 用户要求审查当前 Git 仓库未提交改动、检查 diff 或查找回归时使用。
---
## 工作步骤
1. 查看当前改动，读取相关源码与测试。
2. 根据证据报告问题，说明未覆盖的范围。
## 易错点
`git diff HEAD` 不包含未跟踪文件的正文。
审查未提交改动时，使用 `git ls-files --others --exclude-standard`
列出未跟踪文件，再读取其中与本次审查有关的内容。
这里增加的是具体知识缺口。它没有要求把所有隐藏文件或无关生成文件都读一遍。
怎样检查
先对官网例子逐项问：这条提醒对应什么错误假设？有没有写出具体事实？Agent 能否据此改变查询、字段映射或接口选择？实际验证应使用对应项目中的数据与服务，本页没有运行这些示例系统。
再在本站存在未跟踪文件的练习仓库里，分别运行：
git diff HEAD
git ls-files --others --exclude-standard
再观察使用 Skill 的执行记录：是否意识到第一条命令的覆盖范围，是否补充读取相关文件，是否如实说明没有检查的内容。
本次已在隔离练习中确认：第二条命令列出 untracked-note.txt，第一条命令没有包含它的正文。这个命令行为已验证；Agent 是否遵循新增指令，仍需单独运行模型用例。
完整练习文件见机制参考附录。