Improve writing style with rules in the doc-writer skill

[Alistair Matthews (alistairmatthews)]

Summary

AI-written text in this repo is often identifiably so and this can reduce comprehensibility for our audience. This PR addresses #1792 and implements many of the tropes listed at tropes.fyi. I've left some of those tropes out because I judged them to be helpful in this documentation.

Third-party links and affiliations

None

Validation

I asked Copilot to write some new prose in an article, locally, and observed fewer of these issues.

Fixes: #1792

[Copilot]

Copilot review overview

🟢 Approval recommended

The guidance consistently addresses issue #1792 and is correctly propagated to related documentation workflows.

Review effort: Balanced
Findings: None

What changed in this PR

Adds writing-style guidance to reduce recognizable AI prose patterns and improve documentation clarity, addressing issue #1792.

Changes:

• Adds a comprehensive “Prose patterns to avoid” checklist to the doc-writer skill.
• References the checklist from Astro and Community Toolkit writing instructions.
• Updates the “What’s new” critique/template guidance to avoid em dashes.

File	Description
.github/​instructions/​astro.instructions.md	Requires documentation prose to follow the new checklist.
.github/​agents/​community-toolkit-integration-doc-writer.agent.md	Applies the checklist to integration documentation.
.agents/​skills/​whatsnew/​references/​whats-new-template.mdx	Replaces an em dash in the SEO title example.
.agents/​skills/​whatsnew/​references/​03-critique.md	Adds the checklist to release-note critique criteria.
.agents/​skills/​doc-writer/​SKILL.md	Defines prose structures, wording, tone, and formatting to avoid.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[David Pine (IEvangelist)]

Nice work on this, the rules read well and match what we've been seeing in drafts.

One suggestion on placement: with this change doc-writer/SKILL.md grows to ~1,190 lines (~52 KB), the largest skill in .agents/skills. The new "Prose patterns to avoid" section starts ~37 KB into the file, and agent file reads typically truncate around 20 KB unless the agent asks for a specific range. So the rules most likely to change output are the ones least likely to be read.

Could we:

1. Move the section to .agents/skills/doc-writer/references/prose-patterns.md (same pattern as references/terminal-recordings.md and the whatsnew references).
2. Add a short pointer near the top of SKILL.md, for example: "Before finishing any draft, check it against references/prose-patterns.md."
3. Point the three cross-references in this PR (whatsnew/references/03-critique.md, the toolkit doc-writer agent, and astro.instructions.md) at the new file.

Splitting the rest of SKILL.md (integration templates, testing, cross-referencing, common issues) into references can be a follow-up so it doesn't hold this PR up.

Two smaller things:

• The em dash and parenthesis rule should probably say it applies to new or edited prose. Existing docs have ~1,900 — uses, and without that note the critique step will flag every page it touches.
• astro.instructions.md loses its trailing newline.

[Alistair Matthews (alistairmatthews)]

Nice work on this, the rules read well and match what we've been seeing in drafts.

One suggestion on placement: with this change doc-writer/SKILL.md grows to ~1,190 lines (~52 KB), the largest skill in .agents/skills. The new "Prose patterns to avoid" section starts ~37 KB into the file, and agent file reads typically truncate around 20 KB unless the agent asks for a specific range. So the rules most likely to change output are the ones least likely to be read.

Could we:

1. Move the section to `.agents/skills/doc-writer/references/prose-patterns.md` (same pattern as `references/terminal-recordings.md` and the `whatsnew` references).

2. Add a short pointer near the top of `SKILL.md`, for example: "Before finishing any draft, check it against [references/prose-patterns.md](./references/prose-patterns.md)."

3. Point the three cross-references in this PR (`whatsnew/references/03-critique.md`, the toolkit doc-writer agent, and `astro.instructions.md`) at the new file.

Splitting the rest of SKILL.md (integration templates, testing, cross-referencing, common issues) into references can be a follow-up so it doesn't hold this PR up.

Two smaller things:

* The em dash and parenthesis rule should probably say it applies to new or edited prose. Existing docs have ~1,900 `—` uses, and without that note the critique step will flag every page it touches.

* `astro.instructions.md` loses its trailing newline.

All done. Prose patterns to avoid was also a subsection of AppHost Language Parity, which might have led Copilot to only avoid those patterns when writing about AppHosts. I'll raise an issue to split the rest of the doc writer skill.