writing_skill

Overview

This skill defines clear, concise writing standards for documentation, comments, commit messages, and technical communication. It focuses on brevity, active voice, and scannable structure so technical content is easy to read and act on. Follow these rules when producing READMEs, PRs, error messages, API docs, and code comments.

How this skill works

The skill inspects writing against a compact set of principles: be concise, use active voice, one idea per sentence, and lead with results. It enforces naming clarity, removes redundant terms, and prescribes minimal, structured formats for READMEs, commits, PRs, and error messages. Use the checklists and examples to rewrite or evaluate existing text.

When to use it

• Writing or revising README files and project documentation
• Composing commit messages and pull request descriptions
• Adding or reviewing code comments and inline documentation
• Drafting API docs, error messages, and user-facing text
• Preparing technical proposals, design docs, or release notes

Best practices

• Start with the result or purpose; put conclusions first
• Write short sentences (one idea per sentence) and cut redundant words
• Prefer active voice and imperative mood for commit messages
• Use specific, descriptive names; avoid vague terms like "data" or "item"
• Comment only when necessary: explain why, not what
• Keep examples minimal, real, and focused

Example use cases

• A README: one-sentence purpose, one-paragraph motivation, clear usage steps, compact examples
• A commit: 'Fix payment validation error' instead of vague or past-tense messages
• A PR description using the What/Why/Testing structure for quick review
• An error message: 'Payment failed. Retry or contact support.' not 'An error occurred.'
• API doc: purpose, parameter types, return type, example, and error cases