skills.rest
thedutchvisiongroup
thedutchvisiongroupOFFICIAL
Explore all skills by this author →
WebsiteGitHub

writing-adrs

Creates and validates Architecture Decision Records using MADR 4.0 with OKF YAML frontmatter.

Updated Mar 28, 2026
Search Tags:#documentation#validation#adr#yaml frontmatter#architecture decision record#madr#okf
One-click install
npx skills add https://github.com/thedutchvisiongroup/agent-skills --skill writing-adrs-thedutchvisiongroup
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: writing-adrs
Source: https://github.com/thedutchvisiongroup/agent-skills/tree/main/skills/writing-adrs
Command: npx skills add https://github.com/thedutchvisiongroup/agent-skills --skill writing-adrs-thedutchvisiongroup

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) and references (resource) components.

What problem does it solve? Architectural decisions often go undocumented or are recorded inconsistently, making it impossible for teams to understand why choices were made. This Skill standardizes the creation, validation, and lifecycle management of Architecture Decision Records (ADRs) so every decision is captured in a consistent, machine-readable format. ## Core Features & Use Cases - Structured ADR Authoring: Combines OKF-compliant YAML frontmatter (type, title, deciders, status, generated provenance) with a MADR 4.0 body covering context, options, and outcomes. - Lifecycle Management: Handles the full status lifecycle (proposed, rejected, accepted, deprecated, superseded) including bidirectional supersede links and per-directory numbering that is never reused. - Automated Validation: Ships a Python validator that checks frontmatter fields, required MADR sections, filename conventions, and title/H1 consistency for single files or entire directories. - Use Case: After merging a pull request that switches the database from MySQL to PostgreSQL, ask the agent to document the decision; it discovers the existing ADR directory, assigns the next sequence number, drafts the ADR from git diffs, and validates it. ## Quick Start Ask the agent to create an ADR documenting why the project adopted PostgreSQL, and have it validated with the included script.

Frequently Asked Questions about writing-adrs

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

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

Combine OKF YAML frontmatter (type, title, description, tags, deciders, status, generated) with a MADR 4.0 body containing Context and Problem Statement, Considered Options, and Decision Outcome sections. Save it as NNNN-kebab-case-title.md in your ADR directory and update the index.

How do I validate ADR files automatically?▼

Run the bundled validate_adr.py script with python3 against a single ADR file or an entire directory. It checks frontmatter fields, required MADR sections, filename conventions, and title/H1 consistency, skipping reserved files like index.md and log.md.

How do I supersede an existing ADR?▼

Create a new ADR with the next sequence number linking back to the old one, then set the old ADR's status to superseded with a superseded_by path and update both rows in index.md. Never delete the old ADR or reuse its number.

Where should ADR files be stored in a project?▼

Place ADRs near the code they affect, such as src/database/adr/ for database decisions, or docs/adr/ at the repo root for project-wide decisions. The skill discovers existing ADR locations by searching common patterns before creating new directories.

When should I not write an ADR?▼

Skip ADRs for trivial, reversible, single-developer decisions where a code comment suffices, for decisions already covered by existing standards or policies, and for temporary workarounds or experiments that will not ship to production.

Related Skills

Explore More Software Engineering Skills→
olivermorgan2olivermorgan2

adr-writer

Draft standardized Architectural Decision Records as markdown files in a git repository.

Community
Advanced
learnn-comlearnn-com

capability-verify-done

Validates pull requests against Definition of Done criteria and project adoption files.

Official
Advanced
pvliesdonkpvliesdonk
3

documentation-patterns

Standardize project documentation with ADR templates and Google-style docstrings.

Community
Intermediate
scanadyscanady

tech-arch-architecture-decision-records

Create and index Architecture Decision Records using MADR and other templates.

Community
Advanced