Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.
Detected risks:
The documentation-and-adrs skill helps teams capture and maintain high-value technical documentation focused on architectural decisions, design rationale, and long-term project context. Rather than documenting only implementation details, this skill emphasizes preserving the reasoning behind technical choices, including constraints, trade-offs, rejected alternatives, and expected consequences. It is designed to support maintainability and continuity by ensuring future engineers and AI agents can understand not just what was built, but why specific decisions were made.
The skill provides structured guidance for writing Architecture Decision Records (ADRs), including lifecycle management, standardized templates, and best practices for documenting significant technical decisions. It covers scenarios such as selecting frameworks, databases, authentication strategies, infrastructure platforms, or API architectures. In addition to ADRs, the skill promotes effective inline documentation practices by encouraging comments that explain non-obvious intent rather than restating code behavior. It also outlines situations where documentation should be avoided, such as self-explanatory code or temporary prototypes.
This skill is intended for software engineers, technical leads, architects, and development teams working on long-lived or collaborative codebases. It is especially useful during feature delivery, API changes, architectural refactors, onboarding processes, and infrastructure planning. Teams adopting this approach can improve knowledge sharing, reduce repeated explanations, preserve historical context, and make future technical decisions easier to evaluate and maintain.
An ADR should be written when making significant technical decisions such as selecting frameworks, designing database schemas, choosing infrastructure platforms, or defining API architectures that would be costly to reverse later.
The skill prioritizes documentation that explains the reasoning behind decisions, including context, constraints, trade-offs, and alternatives considered, rather than documenting obvious implementation details.
Yes. The skill includes a structured ADR template with sections for status, date, context, decision, alternatives considered, and consequences, along with guidance for organizing ADR files sequentially.
Yes. The skill provides guidance for writing meaningful inline comments that explain non-obvious intent or design reasoning while discouraging comments that simply restate the code.
The approach is not intended for documenting trivial, self-explanatory code or temporary prototypes. It focuses on preserving valuable long-term context rather than generating excessive or redundant documentation.
Quick Setup:
.claude/skills/Repository
addyosmani/agent-skills