code-documentation

This skill provides a robust framework for managing technical documentation within software projects. Designed for developers, technical writers, and AI agents, it ensures that project documentation remains consistent, readable, and up-to-date. By adhering to structured templates, users can reduce cognitive load during onboarding and improve codebase maintainability. The tool enforces the principle of keeping documentation close to the code, facilitating better developer experience and more reliable knowledge sharing.

• Standardized README templates for quick starts, installation, usage, configuration tables, and contribution guidelines.

• Automated support for JSDoc/TSDoc annotations to generate clear API references from source code.

• Native support for OpenAPI and Swagger specifications to document RESTful endpoints and request/response schemas.

• Structured Architecture Decision Record (ADR) templates to track technical decisions, context, rationales, and consequences.

• Inline comment guidelines to distinguish between explaining 'why' (business logic, workarounds) versus 'what' (obvious code blocks).

• Component-level documentation standards for managing modules, data flows, and external dependencies.

• Integrate this skill into your CI/CD pipeline or development workflow to force consistency across microservices or libraries.

• Prioritize writing examples over exhaustive explanations to keep documentation actionable.

• Use progressive disclosure: provide a concise README quick-start for new users and link to deeper API references for power users.

• Always keep technical documentation in the same repository as the implementation to ensure updates are synchronized with feature changes.

• Avoid redundant comments; focus on capturing design intent, HACKs, TODOs, and complex business rules that aren't immediately evident from function signatures.

• Utilize markdown-based ADRs to maintain a historical record of project evolution, which is invaluable for long-term architectural stability.