Split four sections of the doc-writer skill into reference files

[Alistair Matthews (alistairmatthews)]

Summary

The PR moves the following sections from the doc writer SKILL.md file into reference files:

• Integration Documentation
• Testing Your Documentation
• Cross-Referencing
• Common Documentation Issues

Links to all four new reference files are included in SKILL.md.

This ensures that, when agents load the doc-writer skill, they apply these four sections reliably. When SKILL.md files become as large as it was, agents sometime don't load the entire skill.

Fixes: #1811

Third-party links and affiliations

None

Validation

I asked Claude to check that an agent using the doc-writer skill would be able to access and use all the reference files. The response was:

An agent using the doc-writer skill can now reach all six reference files.

• Links: Each file has exactly one link in SKILL.md, and every path points to a file that exists. The new cross-referencing link is at SKILL.md:12, and terminal-recordings.md is linked at SKILL.md:678.
• Content: All six files are different from each other, and each starts with the right heading.
• No leftovers: The old section is gone from SKILL.md, so the guidance isn't in two places.
• Links inside the reference files: None of the six files has a relative link, so nothing broke when they moved into references/.
• Git: Your fix is committed as b738d4c, and the folder has no uncommitted changes.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 3 · 1

Open (4)

• This table uses a double leading pipe (||), which many Markdown renderers interpret as an extra… · New
• The Playwright command example uses <relevant-spec>.ts, but the file pattern specified just above… · New
• The Playwright command example uses <relevant-spec>.ts, but the file pattern specified just above… · New
• There are a couple of grammatical/wording issues in the new link intro lines: (1) 'Cross… · New

What changed in this PR

This PR reduces the size of the doc-writer skill by moving four large guidance sections out of SKILL.md into dedicated reference files and linking to them from the skill entrypoint.

Changes:

• Added four new reference files under .agents/skills/doc-writer/references/ for integration docs, testing, cross-referencing, and common issues.
• Updated .agents/skills/doc-writer/SKILL.md to link to the new references and removed the inlined sections.

File	Description
.agents/​skills/​doc-writer/​SKILL.md	Adds links to the new reference files and removes the large inlined guidance blocks to keep the skill smaller.
.agents/​skills/​doc-writer/​references/​integration-documentation.md	New reference containing integration doc location + structure templates.
.agents/​skills/​doc-writer/​references/​testing-your-documentation.md	New reference describing validation strategy, test expectations, and local testing workflow.
.agents/​skills/​doc-writer/​references/​cross-referencing.md	New reference describing how to link to docs, use ApiReference, and format “See also”.
.agents/​skills/​doc-writer/​references/​common-documentation-issues.md	New reference compiling common PR feedback rules for docs authoring.

---

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