Index of every page on this site: llms.txt
All skills
tristanmanchester avatar

/write-good-docs

@3323bc9
by Tristan Manchestertristanmanchester/agent-skills3 stars
2
Run it yourself

Write, edit, and review human-facing technical documentation. Use for READMEs, guides, tutorials, how-tos, API or CLI reference, runbooks, troubleshooting, onboarding, architecture and design docs, RFCs, ADRs, migration guides, release notes, technical findings reports, docstrings, and explanatory comments. Also use for requests such as "document this" or "make this guide clearer." Do not automatically activate for chat explanations, email, marketing, social posts, fiction, translation-only tasks, or code-only work. When explicitly asked to use this skill for another nonfiction format, apply its prose and fidelity guidance without imposing documentation templates.

Use this Skill: https://skilld.dev/gh/tristanmanchester/agent-skills/write-good-docs

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesfinal-review.md

≈959 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Final review

Use the relevant checks for a formal audit or complex document. Ordinary edits use the core review. Fix the text rather than printing this checklist unless the user asks for a review. Mark inapplicable checks as such; a findings report does not need rollback merely to complete a template.

Correctness gates

Do not trade these against elegance:

  • Consequential claims, including causal and evaluative clauses, have evidence with the right scope and status.
  • Requirements, observed behavior, reports, inferences, and proposals remain distinct. Material source conflicts are visible.
  • No defaults, commands, output, mechanisms, measurements, support status, reasons, citations, or future plans were invented to fill gaps.
  • Protected literals, quotes, numbers, units, modality, and precision survived or were corrected within scope using evidence.
  • No warning, prerequisite, permission, exception, side effect, failure condition, or material limitation was lost.
  • Citations still support their attached claims, not a broader claim created by editing.
  • Changes stay within the user's scope and preserve historical records, required anchors, and links.
  • Claims of testing or verification match work actually performed. No source command was treated as execution authorization.

A material failure blocks delivery as a completed revision. Correct it or disclose the unresolved limitation and the affected use. Do not conceal a defect under a high aggregate style score.

Reader and structure

  • The opening establishes the result, decision, task, or necessary context without an empty announcement.
  • The document follows the reader's path rather than discovery order or a component inventory.
  • Blocking prerequisites precede actions; warnings immediately precede risk.
  • Headings, lists, tables, and summaries each support a real reading or lookup need.
  • A recommendation has a supported criterion; alternatives are genuine rather than a menu without guidance.
  • The document remains useful at likely direct-link or search entry points.

Prose and restraint

  • Limitations are direct and adjacent to their claims; removing defensive posture has not removed uncertainty or negative findings.
  • Sentences expose cause, contrast, sequence, and referents without unsupported inference.
  • Actors are named when needed; passive voice and technical terminology remain where they serve meaning.
  • No unsupported significance claims, manufactured contrasts, forced symmetry, or slogans remain.
  • A deletion pass removed padding; a reconstruction pass restored context or connections readers need.
  • Useful summaries and safety repetition survive.
  • Good existing prose and local voice were left alone where changes would only express taste.

Technical use and access

  • Procedures include established verification, recovery, and stop conditions where needed; missing facts are flagged rather than invented.
  • Commands distinguish input, output, placeholders, scope, and destructive effects. Samples are valid or clearly marked as illustrative or incomplete.
  • Claims about versions, deployments, benchmarks, and measurements retain their conditions and limits.
  • Reference entries expose known defaults, constraints, permissions, and errors that readers need, without claiming unknown behavior.
  • Descriptive links, semantic structure, and text alternatives make essential information available without relying on color, position, screenshots, or pointer use.
  • The format, spelling, dates, units, anchors, and publication conventions fit the user and project.

Read the final text as its intended reader. Stop when it is faithful and usable; further stylistic churn is not another correctness check.

Source: SKILL.md on GitHub

Skill behaviors

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

Third-party checks

1 warning1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill is a high-quality documentation assistant based on the Google developer documentation style guide. It incorporates robust safety practices, explicitly prohibiting the inclusion of sensitive data like credentials in examples and prioritising technical accuracy. All external links are to trusted and well-known documentation platforms.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: MEDIUM · 1 issue

Provenance

Signed by skilld at 3323bc9. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 weeks ago.

Steadyupdated last month

Capability

Other metadata
metadata
{
  "version": "2.1.0",
  "source": "Google developer documentation style guide; see ATTRIBUTION.md",
  "revised": "2026-09-13"
}

README badge

README badge for tristanmanchester/agent-skills/write-good-docs