Small changes to writing-docs skill

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

@@ -1,11 +1,9 @@
 ---
 name: writing-docs
 description: >-
-  House style for docstrings, code comments, and `Changed in`/`New in` version
-  markers in music21. Use whenever you write or edit a docstring or comment, add
-  a version marker, or decide where a bug fix's test belongs. Covers the length
-  target, the rule against narrating bugs you just fixed, and why regression
-  cases go in unittests rather than doctests.
+  House style for music21 prose: docstrings, comments, and `Changed in`/`New in`
+  markers. Read before writing any of them. Sets the length target, the voice,
+  and where a bug fix's test belongs.
 ---
 
 # Writing docs and comments
@@ -98,6 +96,9 @@ scramble "Chaminade", not "puppy". If you cannot think of a reason a musician wo
 Describe what a parameter is and does in English if it is not obvious; type alone is not
 documentation.
 
+Lead with the thing itself: "Returns the pitches sounding at an offset," not "This method
+can be used to obtain the pitches that are sounding."
+
 No dull repetition in docs. A bit of humor is welcome in docs; the docs are written
 for humans who will close the window if they are dull.  If seven methods do essentially the same thing, give extensive docs the first time and then later methods can refer back to the first method. Don't repeat the same docs over and over.
 
@@ -139,5 +140,7 @@ comments in shipping code, not to tests.
 - When wording is dictated to the agent to substitute for original wording, use it. Do not add parentheticals. Only fix obvious typos.
 - No weapon-metaphors or overly militaristic language. Avoid "blast radius", "rearm", "landmine",
      "detonate" in issues/PR/code.  Trigger or fire events is so commonly used that they're okay.
+- Vary sentence length; three medium declaratives in a row is where the eye slides off the page. Cut throat-clearing — "It is important to note that", "Note that in general" — and start at the verb.
+- A joke needing a second sentence to land is one sentence too long. `Cannot determine sharps for quarter-tone keys! silly!` is the register.