skills.rest
real-case
real-caseCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

adr

Drafts structured Architecture Decision Records in MADR or Nygard format.

Updated Apr 16, 2026
Search Tags:#design#documentation#adr#mcp#technical decisions#architecture decision record#madr
One-click install
npx skills add https://github.com/real-case/marvin-toolkit --skill adr-real-case
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr
Source: https://github.com/real-case/marvin-toolkit/tree/main/plugins/marvin/skills/adr
Command: npx skills add https://github.com/real-case/marvin-toolkit --skill adr-real-case

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Significant technical decisions often go undocumented or are recorded inconsistently, leaving future maintainers without the rationale behind framework, database, or pattern choices. This Skill produces a complete, convention-matching Architecture Decision Record with explicit decision drivers, alternatives, and consequences. ## Core Features & Use Cases - Corpus-aware drafting: Discovers existing ADRs via the adr MCP tool, matches the corpus's style and header format, and reserves the next number and target path automatically. - Structured decision analysis: Gathers context from dependencies, configs, git history, and project conventions, then weighs alternatives against explicit decision drivers. - Governed lifecycle: Drafts always land with status proposed; ratification and supersession stay with the human-run /marvin:adr-accept and /marvin:adr-supersede commands. - Use Case: After choosing PostgreSQL over MongoDB for a new service, run the skill to produce a numbered ADR with context, drivers, honest pros and cons of each option, risks with mitigations, and an updated corpus index. ## Quick Start Ask the assistant to write an ADR for your decision, for example: "write an ADR for adopting event-driven messaging with Kafka".

Frequently Asked Questions about adr

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

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

Invoke the skill with a decision title, and it gathers context from your codebase, dependencies, and git history, then drafts a full ADR with decision drivers, alternatives, and consequences. You review and approve the draft before it is written to disk.

What format does an ADR use, MADR or Nygard?▼

The skill supports both MADR-style sections and Nygard-style table headers. It reads existing records in your corpus and matches their established format, falling back to a default template when the corpus is empty.

Can I create an ADR with accepted status directly?▼

No. Drafts always land with status proposed by design. Ratification is a separate human-run step via the adr-accept command, which also enforces readiness gates like complete sections and valid cross-references.

How are ADR numbers and file paths assigned?▼

The adr MCP tool assigns the next number and exact target path based on your configured or detected corpus directory, such as docs/adr. Numbers are never hand-assigned, preventing collisions and malformed filenames.

What happens when a new decision replaces an old ADR?▼

Draft the new record normally without editing the old one. After it lands, run the adr-supersede command, which deterministically links the two records and flips the old record's status.

Related Skills

Explore More Software Engineering Skills→
remiverdiesenremiverdiesen
6

ark-research

Collect, organize, and evaluate technology options from diverse sources.

Community
Basic
fagemxfagemx

wusanto-scribe

Standardize acceptance and gate review for AI-generated deliverables.

Community
Advanced
Elijah-JElijah-J

write-wiki-page

Draft, revise, or audit technical wiki pages under output/wiki using local corpus docs.

Community
Advanced
lilmuckerslilmuckers

wiki-first-product-management

Organize project definition and architecture in the GitHub wiki.

Community
Intermediate