diff --git a/.agents/skills/write/SKILL.md b/.agents/skills/write/SKILL.md index 24195efc42..b4173ad349 100644 --- a/.agents/skills/write/SKILL.md +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index 9d33bbadef..6d7199a746 100644 --- a/AGENTS.md +++ b/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