code-documentation_skill

Overview

This skill helps teams write clear, maintainable code documentation: READMEs, API references, inline comments, ADRs, and component guides. It focuses on audience-first writing, practical examples, and keeping docs close to code to prevent rot. Use it to produce consistent templates and actionable documentation that developers actually read.

How this skill works

I generate documentation artifacts from common patterns and best practices: standard README templates, JSDoc/TSDoc or OpenAPI snippets for APIs, inline comment guidelines, architecture decision records, and component-level docs. Provide the codebase context or function signatures and I produce ready-to-use docs, examples, and configuration tables. I emphasize examples, progressive disclosure, and instructions that map directly to code and deployment.

When to use it

• Creating a project README that helps new contributors get started quickly
• Authoring API reference docs (JSDoc/TSDoc or OpenAPI/Swagger)
• Writing or cleaning up inline comments and code-level explanations
• Documenting architecture decisions and component responsibilities
• Converting code comments into user-facing developer guides or examples

Best practices

• Write for the audience: quick start for newcomers, deep details for maintainers
• Keep docs near the code and update them alongside changes
• Prefer short, runnable examples over long prose
• Explain why, not what, in inline comments; avoid stating the obvious
• Use structured templates (README, API, ADR) to ensure consistency

Example use cases

• Generate a README with installation, usage, config, and contribution sections
• Produce JSDoc comments for a set of exported functions and types
• Create an OpenAPI spec for REST endpoints from route definitions
• Draft an ADR that records a database technology choice and rationale
• Rewrite noisy inline comments into concise why-focused notes and TODOs