documentation-and-adrs
This skill guides you to document decisions that matter—architectural choices, API shifts, and feature launches—by capturing the reasoning, constraints, and alternatives considered. It includes templates for Architecture Decision Records (ADRs) that preserve historical context, inline documentation patterns that explain intent rather than restating code, and structures for API and README documentation that help current and future engineers understand not just what was built, but why.
Documentation and ADRs records architectural decisions and their reasoning so future engineers understand the why behind technical choices.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-07-26
Documentation and ADRs records architectural decisions and their reasoning so future engineers understand the why behind technical choices. This skill guides you to document decisions that matter—architectural choices, API shifts, and feature launches—by capturing the reasoning, constraints, and alternatives considered. It includes templates for Architecture Decision Records (ADRs) that preserve historical context, inline documentation patterns that explain intent rather than restating code, and structures for API and README documentation that help current and future engineers understand not just what was built, but why.
Use it when
- documentation-and-adrs recommends ADR templates with these core sections: a clear title, status (proposed/accepted/superseded).
- documentation-and-adrs emphasizes that code shows what was built, but rationale explains why.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
addyosmani/agent-skills/documentation-and-adrs · repository language: JavaScript
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write architecture decision records?
documentation-and-adrs guides you to create ADRs that capture the reasoning behind architectural choices. An ADR records a decision, its context (constraints and alternatives considered), and the consequences of choosing that path. Rather than just documenting what was built, ADRs preserve why that choice was made, preventing repeated debates and helping future developers understand the trade-offs your team weighed. Use templates that include title, status, context, decision, and consequences sections.
What should an ADR template for technical decisions include?
documentation-and-adrs recommends ADR templates with these core sections: a clear title, status (proposed/accepted/superseded), context explaining constraints and alternatives, the decision itself, and consequences (both positive and negative). This structure ensures you capture not just what you chose, but why you rejected other options and what impact your choice has. Templates help teams establish consistent documentation conventions for both human and agent collaboration.
Why document design rationale instead of just the code?
documentation-and-adrs emphasizes that code shows what was built, but rationale explains why. Documenting trade-offs and alternatives prevents your team from re-debating settled decisions and helps new engineers understand constraints that may no longer be obvious. Inline documentation focused on intent rather than restating syntax, combined with ADRs for major decisions, captures the reasoning that code alone cannot convey.
When should you write an ADR?
documentation-and-adrs suggests writing ADRs for significant architectural choices, API design decisions, major technology shifts, and feature launches that involve trade-offs. ADRs are most valuable when a decision affects multiple systems, has long-term consequences, or involves choosing between viable alternatives. Recording these decisions early prevents future confusion and creates a searchable history of your codebase's evolution.
How does documentation-and-adrs help prevent repeated debates?
documentation-and-adrs preserves historical decision context by capturing the constraints, alternatives, and reasoning behind each choice. When a decision is recorded with its rationale and consequences, team members and future developers can reference that context instead of re-litigating the same trade-offs. This creates institutional memory and accelerates onboarding for engineers joining the project.
What documentation conventions does this skill establish?
documentation-and-adrs provides patterns for ADR templates, inline documentation that explains intent, API design documentation, and README structures that help teams collaborate consistently. These conventions ensure that both human developers and AI agents can understand not just what code does, but why architectural choices were made, creating a shared foundation for team and agent collaboration.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
Documentation and ADRs
Overview
Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.
When to Use
- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly
When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.
Architecture Decision Records (ADRs)
ADRs capture the
(truncated - see the full file via the links below)
File tree — 1 file
skills/documentation-and-adrs/SKILL.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Record architectural decisions and their rationale for future reference”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Documentation and ADRs helps teams record the reasoning behind significant technical decisions through structured Architecture Decision Records. Store decisions in `docs/decisions/` with context, alternatives considered, and consequences so future engineers and AI agents understand not just what was built, but why.
Create and maintain Architecture Decision Records that capture the reasoning behind significant technical choices. This skill provides multiple templates—from standard MADR format to lightweight Y-statements—and guidance on when ADRs matter most, helping teams establish clear decision-making processes and onboard members through documented architectural history.
Capture significant technical choices in a structured format that explains the problem, alternatives weighed, and reasoning behind your decision. Use the provided template to create numbered records in your docs folder, then reference them from code comments when relevant. This ensures your team understands not just what was decided, but why—making it easier to revisit or build on those choices later.
This skill provides templates and guidance for creating Architecture Decision Records—lightweight documents that preserve the reasoning behind major technical choices. It walks you through the Nygard format, covering context, decision, consequences, and alternatives, plus best practices for lifecycle management and team review. Use it when evaluating trade-offs or recording decisions that shape your system's future.
Architecture Designer guides you through system design from requirements to documented decisions. It creates architecture diagrams, evaluates technology trade-offs, and produces Architecture Decision Records for key choices. Use it to structure microservices, plan scalability, and validate designs with stakeholders.
This skill generates Architecture Decision Records (ADRs) that capture the context, decision, and consequences of significant technical choices. It guides you through gathering essential information, selecting from three formats (MADR, Nygard, or Y-Statement), and produces a structured document that preserves reasoning for future engineers.
More skills Adr Architecture (unlicensed) · architecture-decision (Apache-2.0) · Adr Skill (NOASSERTION)