docs(skill): add brevity guidance to writing-changesets

The skill pushed hard on "concrete detail" and bulleting dense sections
but never said to keep a changeset short or match its length to what the
reader must do — so changesets drifted toward exhaustive PR-depth prose.

Add a "Keep it as short as the change deserves" section: length tracks
the reader's adaptation work, brevity and bullets are complementary (cut
first, then bullet the survivors), and a concrete delete-list for the
usual bloat (verbatim samples, rationale, exhaustive enumerations,
invisible internal filtering, unactionable caveats).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aspiers

.agents/skills/writing-changesets/SKILL.md

@@ -224,6 +224,49 @@ to adapt their environment or code **without reading the PR or
 the source**. Changesets are not release-note marketing copy —
 they are migration instructions.
 
+### Keep it as short as the change deserves
+
+"Concrete" is not "exhaustive". Include exactly what the reader
+needs to adapt, and stop. Most changesets are **two to four
+sentences per audience**; a small change is often a single
+sentence. Length must track the size of what the reader has to do,
+not the effort that went into the change. A one-line behaviour
+tweak gets a one-line changeset even if the PR was large.
+
+Brevity and bullets are not in tension: cutting is about _how many_
+points survive, bullets are about _how you lay them out_ so the
+survivors stay scannable. First cut to the points the reader must
+act on; then, if 3+ remain, lay them out as bullets rather than
+packing them into one paragraph — a short multi-point section is
+still a wall of text when run together. Keep one- or two-point
+sections as inline prose. If you find yourself writing a fourth or
+fifth bullet, that is a signal to cut, not to keep listing.
+
+Before you finish, delete anything the reader does not act on:
+
+- **A verbatim example** (a full log line, a whole JSON body) when
+  naming the fields already tells them what to grep or send. Show
+  a shape only when the exact serialization is the thing they must
+  match.
+- **Rationale and "why" prose** — "since this can signal X", "so
+  that Y". State the observable behaviour; the reasoning belongs
+  in the commit or PR, not the release note.
+- **Exhaustive enumerations** — every endpoint, every reason
+  string, every excluded case — when a representative name plus
+  "and related …" conveys the same adaptation. List the full set
+  only when the reader must match against each member.
+- **Internal filtering the reader never sees** — "3xx are filtered
+  before this runs, 5xx are logged elsewhere". If it doesn't change
+  what they do, it doesn't belong.
+- **Caveats about edge cases** the reader cannot act on. One
+  clause at most; usually cut.
+
+Rule of thumb: if removing a sentence would not change what the
+reader _does_, remove it. A tight four-line changeset that names
+the fields and the observable effect beats a fifteen-line one that
+also explains the mechanism, quotes a sample, and enumerates every
+case.
+
 ### What "concrete detail" means
 
 Good adaptation detail includes: