documentation-and-adrs

What problem does it solve?

This Skill addresses the critical need to capture the rationale behind technical decisions, ensuring long-term project maintainability and clarity for both human and AI collaborators.

Core Features & Use Cases

• Architectural Decision Records (ADRs): Formalizes the process of documenting significant technical choices, including context, alternatives considered, and consequences.
• Inline Documentation Best Practices: Guides on writing effective comments that explain the "why" rather than the "what," and when not to comment.
• API Documentation Standards: Provides examples for documenting public APIs using JSDoc-style comments and OpenAPI/Swagger specifications.
• README Structure: Outlines essential sections for a project's README file to ensure discoverability and ease of onboarding.
• Changelog Maintenance: Offers a template and guidelines for maintaining a clear and informative changelog.
• Agent-Specific Documentation: Highlights the importance of documentation for AI agents, including ADRs and inline comments.
• Use Case: When making a significant architectural choice, like selecting a new database technology, use this Skill to generate an ADR that clearly outlines the reasons for the choice, alternatives considered, and potential impacts.

Quick Start

Use the documentation-and-adrs skill to generate an Architecture Decision Record for a new database choice.