Where are the ADR files saved?

By default, they are saved to docs/adr, but you can define any custom path using the --output argument.

Does it handle ADR numbering automatically?

Yes, the Formatter agent scans your output directory to identify the current sequence and assigns the next appropriate number to the new ADR.

What is the MADR format used by this skill?

MADR stands for Markdown Architectural Decision Records, which is a lean, standardized template for capturing decisions, context, drivers, options, and consequences.

How does the multi-agent pipeline ensure accuracy?

It uses a dedicated Validator agent that cross-references the claims made in the ADR against your actual codebase and source files to identify unsupported assertions.

Can I specify which files the AI should analyze for context?

Yes, you can use the --sources argument to provide a comma-separated list of specific files or directories for the agent to use as grounding data.

Architectural Decision Record Generator

Name: Architectural Decision Record Generator
Author: kbrockhoff

bykbrockhoff

0•

Learning & Documentation

Automates the creation of high-quality Markdown Architectural Decision Records (MADR) through a specialized multi-agent validation pipeline.

The writeadr skill streamlines the critical task of documenting technical architecture by automating the MADR creation process within Claude Code. It utilizes a sophisticated three-stage multi-agent pipeline: a Writer drafts the initial decision record, a Validator verifies technical claims against project source files to prevent inaccuracies, and a Formatter handles sequential numbering and indexing. This ensures that every architectural decision is grounded in project reality, consistently structured, and easily discoverable for current and future team members.

Key Features

01Multi-agent pipeline for drafting, technical validation, and formatting

02Customizable output directories and context-aware source analysis

03Automatic grounding of technical claims against existing source code and documentation

04Standardized MADR (Markdown Architectural Decision Records) template compliance

05Sequential ADR numbering and automated index management

060 GitHub stars

Use Cases

01Recording complex architectural changes in a shared repository for team alignment

02Documenting the rationale behind choosing specific technologies or frameworks

03Maintaining a historical audit trail of technical decisions for compliance and developer onboarding

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add kbrockhoff/brockhoff-tools-claude writeadr

For use in Claude.ai and ChatGPT

Download Skill