Keep a running gotchas list inside each skill
When a skill hits an edge case, append it to a gotchas section in that skill rather than to CLAUDE.md. The lesson then loads only when the skill runs.
The problem
Skills are never right first time. The usual fix is another line in CLAUDE.md, which means every session pays for a lesson that only matters when one particular skill is running.
The hack
Add a `## Gotchas` section to the skill's `SKILL.md`. Each time a run hits an edge case, append it there. Ask Claude to propose the addition and approve it before it writes.
Why it works
The gotcha lives next to the instructions it qualifies, so it loads only when the skill matches. This is the same distinction `/doctor` applies when it trims memory: it cuts what Claude could derive from the codebase and keeps pitfalls, rationale, and conventions that differ from tool defaults.
Setup
1. Add a `## Gotchas` heading to a skill you use often. 2. After a run goes sideways, ask Claude what tripped it up. 3. Have it append a one-line entry — the situation and what to do instead. 4. Approve the edit rather than letting it write unattended. 5. Rerun the skill on the same input and confirm the edge case is handled. 6. Split the skill across several files once the list gets long, so only the needed part loads.
Prompt
That run hit an edge case. Propose a one-line entry for the Gotchas section of this skill describing the situation and what to do instead. Show me the diff before writing it.
Discussion
No comments yet. Be the first to say whether this worked for you.