Why does the skill use pseudocode instead of real code snippets?

The skill prioritizes implementation-agnostic pseudocode to ensure documentation remains focused on high-level design and stays relevant even if the underlying codebase changes.

How does the skill determine the next ADR number?

The skill automatically scans your docs/adr/ directory to identify existing files and increments the highest found number for the new record.

Can I use diagrams in my ADRs?

Yes, the ADR Writer skill supports and encourages the inclusion of Mermaid diagrams and tables to clarify complex architectural designs.

Where does the skill store the ADR files?

By default, this skill saves all records in the docs/adr/ directory using a standardized adr-NNN-description.md naming convention.

What is an Architecture Decision Record (ADR)?

An ADR is a short text file that captures a significant architectural decision, the context in which it was made, and its consequences for the project's future.

Architecture Decision Record Writer

Name: Architecture Decision Record Writer
Author: yaakaito

byyaakaito

•

Learning & Documentation

Generates and manages standardized Architecture Decision Records to document significant design choices and their technical rationale.

The ADR Writer skill automates the creation and maintenance of Architecture Decision Records (ADRs) within your project's repository. It enforces a consistent structure—including context, status, decision details, and consequences—ensuring that the 'why' behind every major architectural shift is preserved for future developers. The skill automatically manages file numbering, directory placement, and naming conventions, while encouraging best practices like documenting trade-offs and using implementation-agnostic pseudocode to describe design patterns.

Key Features

013 GitHub stars

02Standardized templates for context, decisions, and consequences

03Automated ADR file naming and sequential numbering

04Support for Mermaid diagrams and tables for visual documentation

05Enforcement of implementation-agnostic pseudocode for clarity

06Automated discovery of existing ADRs for style consistency

Use Cases

01Recording trade-offs made during a major system refactoring process

02Documenting the rationale for choosing a specific database or framework

03Providing a historical log of design decisions for onboarding new team members

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add yaakaito/env adr-writer

For use in Claude.ai and ChatGPT

Download Skill