Agent skill · tristanmanchester
write-good-docs
Use this skill when the requested output will be human-facing documentation, or when existing documentation must be written, rewritten, shortened, reorganized, or reviewed. Trigger for READMEs, guides, tutorials, how-tos, reference docs, API or CLI docs, runbooks, troubleshooting, onboarding, architecture or design docs, RFCs or ADRs, migration guides, release notes, and docstrings or comments; also trigger on vague requests such as "document this," "write the docs," "clean up this README," or "make this guide clearer." Do not trigger for ad hoc explanations, marketing copy, email, chat, social posts, fiction, or code-only work unless documentation is a material deliverable.
What it needs
About 7k tokens when loaded.
What this skill does
Write good documentation Write for a specific human who needs to understand something, decide something, or complete a task. Produce the shortest document that lets that reader succeed without losing facts, caveats, safety information, or necessary context. This skill governs documentation prose and structure. It is not a source of product facts. Derive facts from the user's material and authoritative project sources. Priorities Resolve tradeoffs in this order: 1. Technical truth and safety. Do not invent, weaken, or silently change facts, requirements, uncertainty, warnings, code, commands, identifiers, or interface labels. 2. The reader's outcome. Include what the intended reader needs to act or understand. Exclude material that serves only the author, implementation history, or an appearance of completeness. 3. Findability and sequence. Make the answer easy to locate, scan, and follow from a search result or direct link. 4. Clarity and concision. Prefer direct, literal, natural language. Remove avoidable friction and repetition. 5. Consistency and mechanics. Follow the user's requirements and the project's established style before this skill's defaults. Do not sacrifice a higher priority to satisfy a lower one. Before writing Use the available context before asking the user for information. 1. Read the request and any supplied source material. 2. When working in a repository, inspect the relevant existing docs, templates, code, tests, configuration, issues, and pull requests. Use the smallest evidence set that establishes the facts and local conventions. 3. Identify: the intended reader; what the reader must understand, decide, or accomplish; what the reader can already be expected to know; the document's primary job; the requested scope, format, length, dialect, and tone. 4. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills tristanmanchester/write-good-docs