skills.rest
Peterson-Benhame
Peterson-BenhameCOMMUNITY
Explore all skills by this author →
GitHub

create-adr

Creates Architecture Decision Records in MADR, Nygard, or Y-Statement formats.

Updated Sep 15, 2026
Search Tags:#documentation#markdown#adr#software architecture#technical decision#architecture decision record#madr
One-click install
npx skills add https://github.com/Peterson-Benhame/agent-skills --skill create-adr-peterson-benhame
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: create-adr
Source: https://github.com/Peterson-Benhame/agent-skills/tree/main/packages/skills-catalog/skills/%28creation%29/create-adr
Command: npx skills add https://github.com/Peterson-Benhame/agent-skills --skill create-adr-peterson-benhame

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose the reasoning behind architectural choices over time, leaving future engineers guessing why a database, framework, or pattern was chosen. This Skill captures the context, decision, and consequences of significant technical choices in a durable, standardized document. ## Core Features & Use Cases - Three Industry Formats: Generates ADRs in MADR (structured options comparison), Nygard (minimal Context/Decision/Consequences), or Y-Statement (single-paragraph) formats. - Automatic Numbering and Naming: Scans your docs/adr/ directory to assign the next sequential number and enforces the NNN-kebab-case-title.md naming convention. - Multilingual Generation: Detects the user's language (English, Portuguese, Spanish) and writes all section headers and content in that language. - Use Case: After deciding to adopt Redis for session storage, ask the agent to record it — it produces ADR-003 with decision drivers, considered options, honest trade-offs, and supersession links. ## Quick Start Ask the agent to write an ADR for a decision your team already made, such as using PostgreSQL as the primary database.

Frequently Asked Questions about create-adr

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

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

State the decision as a noun phrase, then document the context and forces, the chosen option with rationale, and honest positive and negative consequences. This Skill generates the full ADR after asking about format, status, and supersession.

What is the difference between an ADR and an RFC?▼

An RFC drives a decision before it is made by seeking stakeholder approval, while an ADR records a decision after it is finalized for future engineers. The common flow is RFC first, then a decision meeting, then an ADR.

Which ADR format should I use: MADR, Nygard, or Y-Statement?▼

Use MADR when multiple options were seriously evaluated and you want a structured comparison. Use Nygard for quick recording of straightforward decisions, and Y-Statement for compact single-paragraph inline documentation.

Can I generate ADRs in Portuguese or Spanish?▼

Yes, the Skill detects the language of your request and generates all section headers and content in that language. Technical terms like ADR, API, and microservices remain in English where appropriate.

Should I edit an old ADR when a decision changes?▼

No, ADRs are immutable historical records. Create a new ADR and mark the old one as Superseded with a link to the replacement, preserving the context of the original decision.

Related Skills

Explore More Software Engineering Skills→
tech-leads-clubtech-leads-club
5.1k

create-rfc

Generates structured RFC documents with decision criteria, options comparison, and RACI stakeholder roles.

Official
Intermediate
KaakatiKaakati
2

architecture-advisor

Evaluate architectural decisions and generate Architecture Decision Records.

Community
Advanced
VoTruongDanhVoTruongDanh

documentation-templates

Generate standardized templates for READMEs, API docs, and ADRs.

Community
Basic
DagimAlemayehuuDagimAlemayehuu

documentation-and-adrs

Writes architecture decision records, API documentation, READMEs, and changelogs for software projects.

Community
Intermediate