docs: guide agents toward more natural prose (#26143)

## Summary

Agents can produce prose that passes style checks but still sounds
unnatural or takes effort to understand. Add guidance to AGENTS.md and a
required prose review with concrete examples to the write skill.

Broaden the skill to cover PR text, release notes, and other prose,
while keeping its branch and commit workflow specific to documentation
fixes.

Markdown formatting passes. Vale reports only existing findings in
unchanged text; the skill validator rejects the existing `hooks` field.

Generated by Codex

.agents/skills/write/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: write
 description: >
-  Write a documentation fix on a branch. Makes the minimal change, formats,
-  self-reviews, and commits. Use after research has identified what to change.
-  "write the fix", "make the changes", "implement the fix for #1234".
+  Write or edit reader-facing technical prose for immediate comprehension.
+  Use for documentation, PR titles and descriptions, release notes, design
+  documents, user-facing explanations, and substantive comments. Also use
+  when asked to make writing clearer, more natural, less AI-generated, or
+  easier to read. For documentation fixes, handles edits, formatting,
+  self-review, and commits after research identifies what to change.
+  Do not use for code-only tasks with no prose deliverable.
 hooks:
   PostToolUse:
     - matcher: "Edit|Write"
@@ -14,9 +18,37 @@ hooks:
 
 # Write
 
-Make the minimal change that resolves the issue. Research has already
-identified what to change — this skill handles the edit, formatting,
-self-review, and commit.
+Follow the human-readable prose guidance in AGENTS.md and the style rules in
+STYLE.md. Apply the prose review below to every prose deliverable, including
+titles and short comments.
+
+For a prose-only request, return the requested text after reviewing it. Use
+the numbered workflow for a documentation fix after research has identified
+what to change. Branch and commit steps apply to that workflow, not to drafting
+a title, description, or comment. Publishing prose requires authorization
+from the user.
+
+## Prose review
+
+Before returning or committing prose, read it as if explaining the change to
+an experienced colleague. Fix sentences that require a second reading even
+when their grammar is correct. Lint passing does not replace this review.
+
+- Replace invented labels and stacks of nouns with the action or relationship
+  they describe: "post-update configuration validation" becomes "validate
+  the configuration after the update"
+- Use direct verbs: "perform an evaluation of" becomes "evaluate"
+- State concrete behavior instead of vague claims: "improve navigation
+  discoverability" becomes "show the current page in the sidebar" when that
+  is the actual change
+- Keep established technical terms, exact identifiers, and qualifications
+  needed for accuracy. Clarify the surrounding sentence instead of replacing
+  a precise term with a vague one
+- Check titles and headings separately. Use enough words to make their meaning
+  clear without relying on the body to explain an invented label
+
+Make these edits silently. Return the requested prose without a report of
+this review unless the user asks for one.
 
 ## 1. Create a branch
 
@@ -57,7 +89,7 @@ warnings or suggestions remain in its output.
 
 Re-read each changed file: right file, right lines, change is complete,
 front matter is present. Run `git diff` and verify only intended changes
-are present.
+are present. Apply the prose review to the changed text and the commit message.
 
 ## 6. Commit
 

AGENTS.md

@@ -105,6 +105,21 @@ silence individual violations.
 - Don't add a wrong-cased entry to silence one false positive — it
   cascades into `Vale.Terms` violations on every correct usage.
 
+## Human-readable prose
+
+For PR titles and descriptions, documentation, release notes, design documents,
+comments, and other reader-facing prose:
+
+- Write so readers understand the meaning on the first read
+- Use wording that an experienced colleague would plausibly say aloud
+- Prefer verbs and clauses over invented nouns and compressed noun phrases
+- Treat correct grammar as necessary but insufficient for clear writing
+- Before returning prose, silently rewrite wording that is technically
+  interpretable but unnatural or hard to decode
+
+Keep established technical terms and qualifications needed for accuracy.
+Use the write skill's prose review to catch patterns that lint cannot detect.
+
 ## Alpine.js patterns
 
 Do not combine Alpine's `x-show` with the HTML `hidden` attribute on the