dev-communications_skill

Overview

This skill captures the craft of communicating technical concepts clearly to developers. It focuses on building trust through accuracy, transparency, and practical utility rather than marketing spin. Use it to create and evaluate docs that help developers solve real problems quickly and reliably.

How this skill works

The skill inspects developer-facing content—tutorials, API references, getting-started guides, changelogs, code examples, and community messaging—against established patterns and failure modes. Outputs are grounded in the provided reference patterns, sharp-edge diagnostics, and validation rules to ensure documentation is correct, usable, and measurable. It highlights where writers break key principles and recommends concrete fixes to improve time-to-first-success.

When to use it

• Building a new getting-started guide or tutorial
• Writing or reviewing API references and SDK docs
• Drafting changelogs, release notes, or upgrade guidance
• Designing developer onboarding and sample apps
• Evaluating docs for accuracy, working examples, and outcomes

Best practices

• Prioritize accuracy over polish; verify every example against the latest API or SDK
• Show working code and minimal reproducible examples instead of long prose
• Make a clear time-to-first-success path with a working outcome in each tutorial
• Treat error messages and edge cases as part of the documentation surface
• Validate docs against checklist-style rules and run example tests where possible

Example use cases

• Convert a conceptual walkthrough into a short tutorial with a verified sample app
• Review an API reference for missing parameters, unclear return values, or stale examples
• Rewrite a README to emphasize quick success and reduce cognitive load for new users
• Audit release notes to surface breaking changes, upgrade steps, and migration examples
• Create community-facing answers that resolve common developer friction without marketing language