writing-for-a-technical-audience_skill

Overview

This skill helps you write documentation, guides, API references, and other developer-facing content that is clear, concise, and authentic. It enforces practical conventions that reduce AI-like phrasing and improve developer trust. Use it to make technical content easier to scan and more actionable without losing depth.

How this skill works

The skill inspects prose for AI-esque phrases, throat-clearing openings, hedging language, inconsistent terminology, and poor code examples. It flags problems and suggests concrete fixes: shorter sentences, one-concept paragraphs, clear definitions, and a single runnable example with error handling. It also enforces style rules for headings, comments, and error messages to keep docs predictable and useful.

When to use it

• Writing or editing API documentation and reference pages
• Creating tutorials, how-tos, or onboarding guides
• Documenting architecture, design decisions, or tradeoffs
• Producing technical blog posts or engineering notes
• Reviewing technical content for clarity and authenticity

Best practices

• Start with the substance; remove throat-clearing intros
• Use short paragraphs and one concept per paragraph
• Prefer active voice and contractions where natural
• Provide one complete, runnable code example with error handling
• Explain why for design decisions, tradeoffs, or convention breaks
• Choose terms and stick to them; format code and headings consistently

Example use cases

• Rewrite an API reference to include failure modes and return values
• Convert a long tutorial into progressive disclosure: quick start, example, advanced
• Review a docs page to remove AI phrases and hedging language
• Edit code snippets to add realistic error handling and comments
• Standardize headings, error messages, and code comment punctuation across a repo