adr-author
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.
ADR Author helps you write Architectural Decision Records that automated tools and human reviewers can enforce.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-03-28
ADR Author helps you write Architectural Decision Records that automated tools and human reviewers can enforce. 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.
Use it when
- ADR Author teaches you to match enforceability to impact.
- ADR Author emphasizes specificity in each section.
Verify before relying
Read SKILL.md below before installing (3 files). Open directory: indexed for reading, not audited.
Install
delexw/claude-code-misc/adr-author · repository language: HTML
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 do I write architectural decision records that AI can check?
ADR Author helps you structure decisions so automated tools can parse and verify them. The key is specificity: define clear Context (the problem), Decision (what you chose), and Consequences (trade-offs). When you set an enforceability level—HIGH for strict CI checks, MEDIUM for code review gates, LOW for reference—ADR Author guides you to write testable criteria that linting tools and bots can actually enforce, not vague principles.
What enforceability level should my architectural decision have?
ADR Author teaches you to match enforceability to impact. HIGH enforceability suits critical constraints (e.g., "all database queries must use prepared statements")—these go into CI/linting rules. MEDIUM works for team guidelines that need human judgment in code review. LOW is for context-setting decisions that inform future work but don't block it. ADR Author walks you through assessing your decision's scope and team needs to pick the right level.
How do I structure Context, Decision, and Consequences sections effectively?
ADR Author emphasizes specificity in each section. Context should name the actual problem and constraints you faced—not generic background. Decision states what you chose and why, with enough detail that someone unfamiliar with your team understands it. Consequences lists both benefits and trade-offs honestly. This structure lets future developers and automated systems quickly grasp the reasoning, and makes it possible to write enforcement rules that stick.
Can ADR Author help me review existing ADRs for clarity and alignment?
Yes. ADR Author guides you through reviewing existing records against team standards. You'll check whether Context is concrete, Decision is unambiguous, and Consequences are realistic. It also helps you spot ADRs that claim HIGH enforceability but lack the specificity needed for CI tools to verify them—a common gap. This review process ensures your ADR library stays useful and actionable.
How do I make architectural decisions stick with my team?
ADR Author connects documentation to enforcement. Write your decision with the right enforceability level, then integrate it into your CI/code review workflow. HIGH-level ADRs become linting rules; MEDIUM-level ones get linked in pull request templates; LOW-level ones live in your architecture docs. By tying ADRs to actual process gates, you move from "decisions on a wiki nobody reads" to decisions that shape every commit.
What's an ADR template that works with CI and code review tools?
ADR Author provides a template with Title, Status, Context, Decision, Consequences, and Enforceability Level. The enforceability field is crucial—it tells your team and tools how strictly to apply the decision. Add a Verification Criteria section for HIGH-level decisions (e.g., "linter checks for X"). This structure lets you draft ADRs in plain language while keeping them machine-readable, so they integrate smoothly with your existing CI pipelines and review processes.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
ADR Authoring Guide
Help users write Architectural Decision Records that future developers actually read and that automated review systems can enforce. Based on Michael Nygard's format from Documenting Architecture Decisions.
How to Think About ADRs
An ADR captures a decision at a moment in time. It answers: what did we decide, why, and what happens because of it? The audience is a future developer (or an AI reviewer) who encounters code that seems odd and needs to understand the reasoning behind it.
The
(truncated - see the full file via the links below)
File tree — 3 files
skills/adr-author/SKILL.md
skills/adr-author/references/enforceability-patterns.md
skills/adr-author/references/templates.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 › “Write or improve an ADR that future developers and automated systems can understand and enforce”
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 through creating an Architecture Decision Record that captures the reasoning behind significant technical or architectural choices. It follows Michael Nygard's lightweight format to ensure decisions are documented with their context, rationale, and trade-offs—preserving institutional knowledge for future team members. Use it when selecting technologies, establishing development patterns, or documenting constraints that shape your system.
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.
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.
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.
adr-author guides you through structured architecture decision authoring in three phases: Frame captures scope and drivers, Decide evaluates options and rationale, and Govern writes the final ADR file with lineage tracking. Choose between compact Y-Statement or detailed MADR v4.0.0 output, and enter via interactive capture, planner handoff, or template adoption.
Guides you through seven-phase ADR drafting via focused dialogue, asking one question per turn and pressure-testing your reasoning before self-critique. Enforces specificity on components, deciders, and architectural characteristics, then routes to discovery if foundations are shallow.
More skills adr-drafting (MIT) · writing-adrs (MIT)