OpenParable
Skip to content
← Back to skills

Markdown ADRs

Documents

Markdown ADRs is an Agent Skill for documents published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create and maintain MADR-format Architectural Decision Records in Markdown under `docs/decisions`. Use when the user wants to document important decisions.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/documents/markdown-adrs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/markdown-adrs, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

  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.