Maintain Documentation Tone
Use this skill to ensure that all documentation in this repository maintains a consistent, friendly, and enthusiastic voice.
Use this skill when
- The user asks to write, edit, or update a
.mdfile in the documentation. - You are adding a new page to the Astro site.
- The user asks you to review documentation for tone or style.
Do not use this skill when
- Editing strict technical contracts (like OpenAPI specs or internal JSON schemas) where a conversational tone would cause parsing errors or confusion.
- The user explicitly asks for a formal, dry, or academic tone for a specific file (like an official legal disclaimer).
First move
- Read the exact tone requirements and examples located in
references/tone-guidelines.md. - Scan the document you are about to edit to ensure your changes will blend seamlessly with the surrounding text.
Workflow
- Apply the tone guidelines (enthusiastic, accessible, emoji-friendly) to your draft.
- Replace robotic or overly corporate phrasing ("This application executes the initialization sequence") with friendly, human phrasing ("Getting started is a breeze! Just run this command:").
- Ensure formatting uses modern markdown features (bolding for emphasis, bullet points for readability).
Validation
- Check the emojis: Does the section have at least one tasteful, relevant emoji?
- Check the voice: Read the text out loud (in your head). Does it sound like a friendly developer pairing with you, or does it sound like a corporate manual? If the latter, rewrite it.
Examples
- "Update the Quick Start guide to include the new config flag." -> Triggers this skill to ensure the new step is written enthusiastically.
- "Write an ADR for switching to Astro." -> Triggers this skill to ensure the ADR is clear but still approachable.