skills.rest
thomasmartinsen
thomasmartinsenCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

adr-writer

Writes Architecture Decision Records in MADR format from decision context and options.

1|Updated May 19, 2026
Search Tags:#documentation#markdown#adr#software architecture#technical decisions#architecture decision record#madr
One-click install
npx skills add https://github.com/thomasmartinsen/talks --skill adr-writer-thomasmartinsen
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr-writer
Source: https://github.com/thomasmartinsen/talks/tree/main/20260519%20-%20Agentic%20engineering/primitives/skills/dev-docs/skills/adr-writer
Command: npx skills add https://github.com/thomasmartinsen/talks --skill adr-writer-thomasmartinsen

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often lose track of why technical decisions were made, leaving future developers guessing about the reasoning behind architecture choices. This Skill captures decisions, alternatives, and trade-offs in a consistent MADR-format document. ## Core Features & Use Cases - MADR-Formatted ADRs: Generates a complete Architecture Decision Record with status, date, context, decision drivers, considered options, and consequences. - Sequential Numbering: Saves the ADR to docs/decisions/NNNN-title.md, automatically determining the next sequential number. - Interactive Review: Walks through the draft with the user to verify options are represented fairly and trade-offs are captured. - Use Case: After choosing PostgreSQL over MongoDB for a new service, ask the Skill to document the decision — it produces a structured ADR recording the drivers, rejected alternatives, and consequences. ## Quick Start Ask the assistant to write an ADR documenting why you chose a specific technology or approach, providing the context and options considered.

Frequently Asked Questions about adr-writer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an Architecture Decision Record?▼

Provide the decision title, the context or problem, at least two considered options, the chosen option, and its consequences. The Skill fills in a MADR template with status, date, decision drivers, and pros and cons, then saves it to docs/decisions/.

What is the MADR format for ADRs?▼

MADR (Markdown Architectural Decision Records) is a lightweight ADR template with sections for status, context and problem statement, decision drivers, considered options, decision outcome, and pros and cons of each option. It keeps decision documentation consistent and reviewable.

Where are ADR files saved and how are they numbered?▼

ADRs are saved to docs/decisions/NNNN-kebab-case-title.md, where NNNN is the next sequential number in that folder. If no ADRs exist yet, numbering starts at 0001, and the folder is created if missing.

When should I mark an ADR as Proposed instead of Accepted?▼

Use Proposed when the decision is still under discussion or has not been formally ratified; the Skill adds a note clarifying no final decision has been made. Use Accepted once the decision is confirmed, and mark old ADRs as Superseded when revisited.

Can an ADR be generated without interactive back-and-forth?▼

Yes. In non-interactive contexts the Skill infers missing details from the provided information, states its assumptions explicitly in the ADR draft, and skips the interactive review step.

Related Skills

Explore More Software Engineering Skills→
robertdprobertdp

design

Inspect codebases and produce validated implementation plans for software designs.

Community
Advanced
c-tomiokac-tomioka

adr-madr

Generate MADR-compliant architectural decision records from git logs, pull requests, or freeform text.

Community
Intermediate
abudhahirabudhahir

architecture-documenter

Generate system architecture documentation and Architecture Decision Records.

Community
Advanced
cooperacodecooperacode
5

adr

Generate MADR-based Architecture Decision Records from active wiki pages.

Official
Advanced