skills.rest
ttphats
ttphatsCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

create-adr

Generates Architecture Decision Records with context, decision, consequences, and alternatives.

Updated Jan 28, 2026
Search Tags:#documentation#markdown#adr#software architecture#technical decisions#architecture decision record#madr
One-click install
npx skills add https://github.com/ttphats/project-detedxs26 --skill create-adr-ttphats
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: create-adr
Source: https://github.com/ttphats/project-detedxs26/tree/main/.augment/skills/custom/create-adr
Command: npx skills add https://github.com/ttphats/project-detedxs26 --skill create-adr-ttphats

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Technical decisions made during development are often forgotten or poorly documented, leaving future maintainers without context on why a technology or pattern was chosen. This Skill captures those decisions in a structured Architecture Decision Record (ADR) format. ## Core Features & Use Cases - Structured ADR Generation: Produces records with status, context, decision statement, positive/negative/neutral consequences, and alternatives with rejection reasons, based on MADR and Nygard (2011). - Automatic Numbering and Filing: Scans docs/adr/ for existing records, assigns the next ADR number, saves to docs/adr/ADR-{NUMBER}-{slug}.md, and updates the ADR index. - Use Case: After deciding to adopt PostgreSQL over MongoDB in a design discussion, ask for an ADR and receive a complete, numbered record documenting the context, trade-offs, and rejected alternatives. ## Quick Start Ask the assistant to create an ADR documenting your recent technology or architecture decision, providing the title, status, and deciders.

Frequently Asked Questions about create-adr

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

FAQPage Schema
How do I create an architecture decision record?▼

Provide a short title, status (Proposed or Accepted), deciders, and related links. The Skill generates a full ADR with context, a 'We will...' decision statement, consequences, and alternatives, then saves it to docs/adr/ with the next sequential number.

What format does an ADR template follow?▼

The template is based on MADR and Michael Nygard's 2011 format. It includes status, date, deciders, context, decision, positive/negative/neutral consequences, alternatives with pros/cons and rejection reasons, and references.

Where are ADR files stored in a repository?▼

ADRs are saved as Markdown files in docs/adr/ using the naming pattern ADR-{NUMBER}-{slug}.md. The Skill scans that directory to assign the next number and appends the new entry to docs/adr/README.md if an index exists.

When should I write an ADR instead of a design doc?▼

Write an ADR for a single decision such as a technology choice, architecture pattern, or process change, keeping it to one or two pages. Longer analysis, diagrams, and implementation detail belong in a separate design document referenced from the ADR.

What are common mistakes when writing architecture decision records?▼

Common anti-patterns include listing only positive consequences, omitting alternatives, writing context that describes what instead of why, and vague decision statements. Every ADR should include trade-offs and at least two alternatives with rejection reasons.

Related Skills

Explore More Software Engineering Skills→
akvoakvo
2

bmad-architect

Design system architectures and document decisions with Architecture Decision Records.

Official
Advanced
zorgentechzorgentech

adr-approve

Move approved ADR files to docs/adr and update status via GitHub CLI.

Official
Advanced
404kidwiz404kidwiz

document-writer

Generate structured technical documentation including ADRs, RFCs, and system design documents.

Community
Intermediate
camilooscargbaptistacamilooscargbaptista
7

architecture-review-board

Generate RFC templates, review criteria, and decision logs for architecture governance.

Community
Advanced