docs-writer_skill

Overview

This skill defines standards and a workflow for writing, reviewing, and editing project documentation, with emphasis on files under apps/docs/ and any .md/.mdx files. It ensures consistent voice, formatting, structure, and accessibility so documentation is clear, accurate, and easy to maintain. Use it as a checklist and style guide whenever you create or modify docs.

How this skill works

The skill inspects requested doc changes and guides a structured workflow: clarify the request, investigate code and existing pages, plan edits, implement changes, and verify accuracy and links. It enforces voice and grammar rules, formatting and syntax conventions, and a prescribed document structure (BLUF, headings, procedures, next steps). During reviews it highlights gaps, consistency issues, and accessibility items to correct before finalizing.

When to use it

• Writing new documentation pages for apps/docs/ or any .md/.mdx files
• Editing existing documentation to reflect code changes or clarify instructions
• Reviewing docs in a pull request to enforce style and structure
• Preparing documentation for release or public consumption
• Auditing docs for accessibility, links, and accuracy

Best practices

• Start each section with a BLUF introduction paragraph before lists or subheadings
• Address the reader as "you", use active voice, present tense, and contractions
• Use sentence case for headings and bold UI elements; use code font for filenames and code
• Number sequential steps and use bullets for non-sequential items; keep items parallel
• Wrap text at 80 characters, use clear dates, and include descriptive alt text for images
• Run a final check for factual accuracy, link validity, and consistent terminology

Example use cases

• Convert a draft feature overview into a BLUF-led page with step-by-step setup instructions
• Update API docs after a backend change and verify code examples match implementation
• Review a contributor's PR to fix tone, grammar, and heading hierarchy
• Create an 'Experimental features' note for preview functionality
• Audit all .mdx files for missing alt text, incorrect links, or nonstandard headings