architecture-decision-records
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.
Architecture Decision Records helps you document technical decisions with context, rationale, and consequences using proven templates.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-07-22
Architecture Decision Records helps you document technical decisions with context, rationale, and consequences using proven templates. 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.
Use it when
- architecture-decision-records offers several templates including the standard MADR (Markdown Architecture Decision Records) format.
- architecture-decision-records guidance suggests writing ADRs for significant technical choices that affect system design.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
wshobson/agents/architecture-decision-records · repository language: Python
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?
architecture-decision-records helps you create ADRs by providing multiple templates and best practices. Start by identifying a significant technical choice, then document the context (problem statement), decision (what you chose), consequences (trade-offs and impacts), and alternatives considered. The skill supports standard MADR format and lightweight Y-statements, ensuring your team captures reasoning clearly and consistently for future reference.
What is an ADR template for technical decisions?
architecture-decision-records offers several templates including the standard MADR (Markdown Architecture Decision Records) format and Y-statements. MADR typically includes Title, Status, Context, Decision, Consequences, and Alternatives sections. These templates help teams structure decisions uniformly, making it easier to review, compare, and understand the rationale behind architectural choices across your codebase.
When should I write an ADR?
architecture-decision-records guidance suggests writing ADRs for significant technical choices that affect system design, technology selection, or long-term maintainability. Focus on decisions with meaningful trade-offs, those impacting multiple teams, or choices that might be questioned later. Not every decision needs an ADR—reserve them for architectural decisions that warrant documented reasoning and historical context.
How to manage ADRs in a team?
architecture-decision-records supports establishing a decision-making process and governance framework for your team. Implement a review process where ADRs are discussed before finalization, maintain an index of all decisions organized by domain or date, track status (Proposed, Accepted, Deprecated, Superseded), and use ADRs during onboarding to help new members understand historical context and design rationale.
What is the ADR lifecycle and status tracking?
architecture-decision-records enables you to manage ADR lifecycles through status tracking. Decisions typically progress from Proposed (under discussion) to Accepted (approved), then may be Deprecated (no longer recommended) or Superseded (replaced by newer decisions). This lifecycle management helps teams understand which decisions remain active, which have evolved, and provides clear documentation of architectural evolution over time.
How does architecture-decision-records help onboard new team members?
architecture-decision-records captures historical context and design rationale in your ADR index, allowing new team members to quickly understand why architectural choices were made. Rather than relying on tribal knowledge, onboarding becomes systematic—new developers can review the decision history, understand trade-offs, and grasp the reasoning behind current system design through documented architectural records.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
Architecture Decision Records
Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
When to Use This Skill
- Making significant architectural decisions
- Documenting technology choices
- Recording design trade-offs
- Onboarding new team members
- Reviewing historical decisions
- Establishing decision-making processes
Core Concepts
1. What is an ADR?
An Architecture Decision Record captures:
- Context: Why we needed to make a decision
- Decision: What we decided
- Consequences: What happens as a result
2. When to Write an ADR
| Write ADR | Skip ADR |
|---|---|
| New framework adoption | Minor version upgrades |
| Database technology choice |
(truncated - see the full file via the links below)
File tree — 1 file
plugins/documentation-generation/skills/architecture-decision-records/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 › “Create and structure architecture decision records following industry best practices”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
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.
This skill captures architectural decisions made during coding sessions as structured ADR documents that live alongside your codebase. It detects decision moments, gathers context and alternatives, and maintains a searchable log so future developers understand the reasoning behind your architecture.
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 structures architecture decisions by enforcing a rigorous trade-off analysis: context, constraints, at least three viable options, and explicit consequences. It produces formal decision records (ADR/RFC/RFD) that capture both positive and negative outcomes, ensuring decisions remain auditable and reversible.
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.
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.
More skills Adr Architecture (unlicensed) · adr-writer (MIT) · adr (MIT) · Create Adr (NOASSERTION) · Create Adr (NOASSERTION) · Architecture Decision Records (NOASSERTION) · adr-writer (MIT) · adr-decision-extraction (Apache-2.0)