How do I install the Markdown ADRs skill?

Run npx skillmds add majiayu000/markdown-adrs in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Markdown ADRs safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Markdown ADRs?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Markdown ADRs free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Markdown ADRs?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Markdown ADRs by majiayu000 — Agent Skill

Name: Markdown ADRs
Rating: 4.2 (5 reviews)
Author: majiayu000

File contents

MADR ADRs

This skill creates (and keeps tidy) Architectural Decision Records (ADRs) using MADR (Markdown Architectural Decision Records) v4.0.0.

A helpful bar for what “counts” as an architectural decision is Martin Fowler’s: “a decision you wish you could get right early.” ("Who needs an architect?", IEEE Software, 2003)

Primary reference: Markdown Architectural Decision Records

Repository layout and naming

All ADRs live in:

docs/decisions/NNNN-title-with-dashes.md

Where:

NNNN is a zero-padded 4-digit sequence number (0001, 0002, …)
title-with-dashes is a lowercase slug (letters/digits/hyphens)

If docs/decisions/ does not exist yet, create it.

Template

Use this copy of the MADR 4.0.0 long-form template

Create new ADRs by copying the template and replacing placeholders. Optional sections may be removed (the template marks them clearly).

Required metadata

Each ADR must include YAML front matter at the top with:

status: one of proposed, accepted, rejected, deprecated, or superseded by ADR-NNNN
date: YYYY-MM-DD (update when the ADR is materially changed)

Status emoji for the index

Maintain an index at docs/decisions/README.md that lists all ADRs with:

status emoji
ADR title (matching the H1 of the ADR), as a link to the full ADR
date last updated

Use this mapping:

🟡 proposed
✅ accepted
❌ rejected
⚠️ deprecated
🔁 superseded

Process

Pick the next number by scanning existing ADR filenames in docs/decisions/ and incrementing the highest NNNN. Start at 0001 if none exist.
Slugify the title into title-with-dashes (lowercase, hyphens, no punctuation).
Create the ADR from ADR_TEMPLATE.md.
- Default status to proposed unless the change set includes implementation and agreement to accept.
Update docs/decisions/README.md:
- Add the ADR in numeric order.
- Ensure the emoji matches the ADR’s status.
If an ADR is superseded, keep the old ADR file, set its status to superseded by ADR-NNNN, and update the index row emoji to 🔁.

Output expectations

ADR markdown should be clean and readable in GitHub rendering.
Keep ADRs concise, but include enough context that a new reader can understand why the decision was made.

---name: markdown-adrsdescription: Create and maintain MADR-format Architectural Decision Records in Markdown under `docs/decisions`. Use when the user wants to document important decisions.--- # MADR ADRs This skill creates (and keeps tidy) **Architectural Decision Records (ADRs)** using **MADR (Markdown Architectural Decision Records) v4.0.0**. A helpful bar for what “counts” as an *architectural decision* is Martin Fowler’s: **“a decision you wish you could get right early.”** (["Who needs an architect?"](https://web.archive.org/web/20231221064723/https://ieeexplore.ieee.org/document/1231144?arnumber=1231144), IEEE Software, 2003) Primary reference: [Markdown Architectural Decision Records](https://adr.github.io/madr/) ## Repository layout and naming All ADRs live in: - `docs/decisions/NNNN-title-with-dashes.md` Where: - `NNNN` is a **zero-padded 4-digit** sequence number (`0001`, `0002`, …) - `title-with-dashes` is a **lowercase slug** (letters/digits/hyphens) If `docs/decisions/` does not exist yet, create it. ## Template Use this copy of the [MADR 4.0.0 long-form template](ADR_TEMPLATE.md) Create new ADRs by copying the template and replacing placeholders. Optional sections may be removed (the template marks them clearly). ## Required metadata Each ADR must include YAML front matter at the top with: - `status`: one of `proposed`, `accepted`, `rejected`, `deprecated`, or `superseded by ADR-NNNN` - `date`: `YYYY-MM-DD` (update when the ADR is materially changed) ## Status emoji for the index Maintain an index at `docs/decisions/README.md` that lists **all** ADRs with: - status emoji - ADR title (matching the H1 of the ADR), as a link to the full ADR - date last updated Use this mapping: - 🟡 proposed - ✅ accepted - ❌ rejected - ⚠️ deprecated - 🔁 superseded ## Process 1. **Pick the next number** by scanning existing ADR filenames in `docs/decisions/` and incrementing the highest `NNNN`. Start at `0001` if none exist. 2. **Slugify the title** into `title-with-dashes` (lowercase, hyphens, no punctuation). 3. **Create the ADR** from `ADR_TEMPLATE.md`. - Default `status` to `proposed` unless the change set includes implementation and agreement to accept. 4. **Update `docs/decisions/README.md`**: - Add the ADR in numeric order. - Ensure the emoji matches the ADR’s `status`. 5. If an ADR is **superseded**, keep the old ADR file, set its status to `superseded by ADR-NNNN`, and update the index row emoji to 🔁. ## Output expectations - ADR markdown should be clean and readable in GitHub rendering. - Keep ADRs concise, but include enough context that a new reader can understand why the decision was made.

Frequently asked questions