authoring-skillslisted

# Authoring skills — point, don't mirror A skill or rule is loaded into context and *believed*. That is its whole value and its whole danger. So it must bind to things that stay true and never freeze a snapshot of things that move. A skill that *mirrors* the code is a copy that goes stale silently — and a silently-wrong skill is worse than no skill, because Claude trusts the lie and skips reading the code. A skill that *points* at the code stays correct: the pointer re-resolves after the code changes. Three mirror failures recur, each hard to diagnose because the symptom shows up in output while the cause hides in a doc nobody re-reads: a cited file and line that a refactor moved; a step-by-step flow restated as prose after the pipeline was rearchitected; an "exhaustive" roster that someone added to or deleted from. The common thread is a frozen snapshot of a moving target. ## Sort every sentence before it goes in: durable invariant, or perishable snapshot? Bind to the first. Never mirror the second. **Bind to (durable — survives refactors):** - Conventions and contracts — units, ordering, idempotency, null-handling. *"All money is stored in minor units."* *"The importer must be idempotent."* - Gotchas and footguns — library quirks, non-obvious traps. The footgun is still a footgun after the file is renamed. - Navigation — *"the auth logic lives under the auth module."* Point, don't transcribe. - The WHY behind a decision — *"we queue writes because the API rate-limits."