skills.rest
paulpessoa
paulpessoaCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

create-adr

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

3|1|Updated Mar 17, 2022
Search Tags:#documentation#markdown#adr#software architecture#technical decision#architecture decision record#madr
One-click install
npx skills add https://github.com/paulpessoa/menvo --skill create-adr-paulpessoa
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: create-adr
Source: https://github.com/paulpessoa/menvo/tree/main/.agent/skills/create-adr
Command: npx skills add https://github.com/paulpessoa/menvo --skill create-adr-paulpessoa

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 selected. This Skill captures the context, decision, and consequences of significant technical choices in durable, standardized ADR documents. ## 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 and writes the ADR in English, Portuguese, Spanish, or other languages automatically. - Use Case: After deciding to adopt GraphQL over REST, ask the agent to record the decision; it produces a numbered MADR document with considered options, decision drivers, honest trade-offs, and supersession links. ## Quick Start Ask the agent to write an ADR documenting your decision to use PostgreSQL as the primary database, including the alternatives you evaluated and why they were rejected.

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 ADR in MADR, Nygard, or Y-Statement format after gathering any missing details.

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

An RFC drives a decision before it is made by seeking stakeholder input, while an ADR records a decision after it is finalized for future engineers. ADRs are short (200-500 words) and immutable; RFCs are longer and evolve during review.

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

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

Can ADRs be generated 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 product names remain in their original form.

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

No, ADRs are immutable historical records. Create a new ADR that supersedes the old one, mark the old ADR as Superseded, and link both documents to preserve the original context.

When should I not use an ADR?▼

Do not use an ADR when the decision has not been made yet (use an RFC), for implementation planning (use a technical design doc), or for trivial choices like naming conventions and minor configuration values.

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
bwgzbwgz

design-documentation

Translates approved requirements into comprehensive technical designs with architecture diagrams, component interfaces, data models, and decision logs.

Community
Intermediate
sumeetonline90sumeetonline90

architecture-decision-records

Capture architectural decisions as standardized ADR documents with context and rationale.

Community
Intermediate
huangzidahuangzida
2

documentation-and-adrs

Document architectural decisions and ADRs under docs/decisions with sequential numbering.

Community
Intermediate