architecture-decision-record
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 Decision Record helps you document significant architectural decisions using the Nygard format with context, decision, consequences, and alternatives.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-07-28
Architecture Decision Record helps you document significant architectural decisions using the Nygard format with context, decision, consequences, and alternatives. 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.
Use it when
- architecture-decision-record guides you to document each alternative you evaluated before choosing your decision.
- architecture-decision-record recommends creating an ADR whenever you make a significant architectural decision—choices about technology.
Verify before relying
Read SKILL.md below before installing (17 files). Open directory: indexed for reading, not audited.
Install
yonatangross/orchestkit/architecture-decision-record · repository language: TypeScript
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-record provides templates and guidance for creating ADRs using the Nygard format. Start by capturing the context (the issue or problem), then state your decision clearly, document the consequences (both positive and negative), and list alternatives you considered. Include the decision status and date. This lightweight approach preserves your reasoning and helps teams understand why technical choices were made.
What should the ADR alternatives considered section include?
architecture-decision-record guides you to document each alternative you evaluated before choosing your decision. For each option, briefly describe what it is, note its key trade-offs, and explain why you rejected it or chose another instead. This section is crucial for future readers—it shows the thinking process and prevents revisiting dismissed options without good reason.
When should I create an ADR?
architecture-decision-record recommends creating an ADR whenever you make a significant architectural decision—choices about technology, design patterns, or system structure that will shape your codebase's future. Create one when evaluating trade-offs, establishing team consensus on tech choices, or recording decisions that affect multiple teams or long-term maintenance.
How does architecture-decision-record help track decision lifecycle?
architecture-decision-record supports status workflow throughout a decision's life: from proposal through acceptance to supersession. Each ADR records when it was created, who decided, and its current status. When a decision is later replaced, you can link the new ADR to the old one, maintaining a complete history that helps onboarding and prevents losing context about why systems evolved.
What are architectural decision consequences and tradeoffs?
architecture-decision-record emphasizes documenting both positive and negative consequences of your choice. Consequences include impacts on performance, maintainability, team skills, deployment complexity, and future flexibility. Tradeoffs show what you gained versus what you sacrificed—for example, choosing a simpler framework might reduce learning curve but limit scalability. Recording these helps teams make informed decisions later.
Why document architectural decisions with ADRs?
architecture-decision-record helps you maintain architectural history and decision rationale for onboarding and reference. Without ADRs, new team members must reverse-engineer why systems are built a certain way. ADRs preserve context, prevent repeating past mistakes, establish team consensus on design patterns, and create a searchable record that answers 'why was this choice made?' years later.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
Architecture Decision Records
Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions along with their context and consequences. This skill provides templates, examples, and best practices for creating and maintaining ADRs in your projects.
Overview
- Making significant technology choices (databases, frameworks, cloud providers)
- Designing system architecture or major components
- Establishing patterns or
(truncated - see the full file via the links below)
File tree — 15 files
src/skills/architecture-decision-record/SKILL.md
src/skills/architecture-decision-record/assets/adr-template.md
src/skills/architecture-decision-record/checklists/adr-review-checklist.md
src/skills/architecture-decision-record/examples/adr-0001-adopt-microservices.md
src/skills/architecture-decision-record/examples/adr-0002-choose-postgresql.md
src/skills/architecture-decision-record/examples/adr-0003-api-versioning-strategy.md
src/skills/architecture-decision-record/references/adr-best-practices.md
src/skills/architecture-decision-record/rules/_sections.md
src/skills/architecture-decision-record/rules/_template.md
src/skills/architecture-decision-record/rules/interrogation-reliability.md
src/skills/architecture-decision-record/rules/interrogation-scalability.md
src/skills/architecture-decision-record/rules/interrogation-security.md
src/skills/architecture-decision-record/scripts/adr-frontmatter.yaml
src/skills/architecture-decision-record/scripts/adr-manager.py
src/skills/architecture-decision-record/scripts/create-adr.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 document significant architectural decisions with context and consequences”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Create ADRs that capture the reasoning behind significant technical choices, including context, alternatives considered, and trade-offs. The skill guides you through gathering implementation details, identifying decision drivers, and structuring records that help future developers understand why architectural choices were made.
Documentation Patterns offers structured templates for READMEs, Architecture Decision Records, OpenAPI 3.1 specifications, changelogs, and technical writing conventions. Use this skill when establishing documentation standards, onboarding contributors, recording architectural decisions, or maintaining consistent API and release documentation across your projects.
This skill produces structured technical documentation across four types: architectural decision records for design choices, system overviews for onboarding, API references for integrations, and operational runbooks for procedures. It enforces anti-patterns like documentation drift and future fiction while matching detail to audience—from high-level concepts for new developers to procedural steps for operations teams.
Create Adr Spike walks you through a five-phase process—Research, Analysis, Decision, Documentation, and Memory Storage—to evaluate technical alternatives and formalize architectural choices. It manages ADR lifecycle with proper numbering, integrates external research tools, and persists decisions to a memory graph for future reference.
ADR Author guides you through writing Architectural Decision Records that future developers and automated systems can actually enforce. It covers the full workflow from reading existing ADRs to drafting decisions at the right enforceability level—whether you need automated verification, human review, or reference-only documentation.
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.
More skills architecture-decision-records (MIT) · adr (MIT) · Create Adr (NOASSERTION) · adr-writer (MIT) · architecture-designer (MIT) · Adr Architecture (unlicensed) · develop-adr (Apache-2.0) · adr-writer (MIT)