Cold read

Rules

• Current state only. How things used to be, what was migrated or abandoned, what is no longer used — invisible to the doc. A fact that matters only as contrast with the past doesn't matter.
• No references that need history. A name, codename, or decision that only a past conversation explains either becomes a general rule the reader can apply on their own, or goes. If generalizing needs a fact nobody wrote down, cut the line and flag it to the owner — never invent the rationale.
• Nothing obvious. A warning no reader would violate is noise; enforce mechanically instead (.gitignore, lint, CI) and stay silent.
• No meta-commentary. Nothing about how the doc was written or what was agreed along the way — state the rules themselves.
• Explain things at the point of use. A variable, secret, or constant is described where it is used — the skill, module, or config that reads it; a central doc says only where such things come from and how to fetch them.
• English, except literal data — names of external entities (databases, properties, pages) stay exactly as they are spelled there.

• The description is a trigger, not a manual: what the skill does and when to fire it. Implementation details live in the body, loaded only on use.
• Skills are never listed in AGENTS.md / CLAUDE.md — they announce themselves through their own descriptions.

Verify empirically

1. give it scenario questions ("you're asked to do X — walk through what you do") and check it reaches the right actions;
2. ask what confused it, what it needed but couldn't find, and what it read but didn't need.