Verified:GitHub

create-adr

Create auto-numbered Architecture Decision Records in MADR, Nygard, or Y-Statement formats.

Updated Aug 23, 2026

Search Tags:#system design #software documentation #language detection #adrs #decision rationale #architecture decision records

Ready to run

npx skills add https://github.com/luizgmassa/Useful-Agent-Skills --skill create-adr-luizgmassa

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: create-adr
Source: https://github.com/luizgmassa/Useful-Agent-Skills/tree/main/skills/create-adr
Command: npx skills add https://github.com/luizgmassa/Useful-Agent-Skills --skill create-adr-luizgmassa

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill removes the ambiguity of “why we chose X” by turning finalized architectural choices into clear, durable ADRs that future engineers can reference.

Core Features & Use Cases

Auto-numbered ADR creation: Scans your ADR folders to select the next sequential ADR number and enforces naming conventions.
Multi-format ADR output: Generates MADR (recommended), Nygard (minimal), or Y-Statement (compact), based on your context.
Language-aware documentation: Detects the user’s language and writes the ADR with matching section headers and content.
Decision lifecycle support: Collects/validates mandatory fields (title, date, status, context, consequences) and links superseding relationships.

Quick Start

Tell an AI agent: Write an ADR for using PostgreSQL as our primary database, and include the decision status as Accepted.

Frequently Asked Questions about create-adr

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

FAQPage Schema

How do I document architecture decision rationale for a new database selection?▼

Architecture decision rationale is documented by creating an Architecture Decision Record (ADR) that captures the context, decision, and consequences of the database selection. This ensures future teams understand why specific technical choices were made.

What formats can I use to write an Architecture Decision Record?▼

Architecture Decision Records can be written in MADR, Nygard, or Y-Statement formats. MADR is recommended for comprehensive documentation, Nygard offers a minimal structure, and Y-Statement provides a compact alternative based on your context.

How do I manage superseding histories for superseded architecture decisions?▼

Managing superseding histories involves linking superseded architecture decisions to their superseding records. The ADR creation process validates mandatory metadata and enforces these sequential relationships to maintain a clear decision lifecycle.

Does ADR creation support language adaptation for non-English documentation?▼

ADR creation supports language adaptation by detecting the user's request language. It automatically generates the architecture decision record content and section headers to match the requested language.

How do I auto-number ADRs across existing software documentation folders?▼

To auto-number ADRs, the system scans your existing ADR folders to identify the next sequential number. It then enforces naming conventions to ensure consistent software documentation ordering.