adr-writer

Create and update Markdown Architecture Decision Records with validated front matter.

Updated Mar 22, 2026

Search Tags:#architecture #documentation #markdown #adr #obsidian #governance #decision-record

Ready to run

npx skills add https://github.com/fabioabr/rag-blueprint --skill adr-writer-fabioabr

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: adr-writer
Source: https://github.com/fabioabr/rag-blueprint/tree/main/src/.claude/skills/adr-writer
Command: npx skills add https://github.com/fabioabr/rag-blueprint --skill adr-writer-fabioabr

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

ADRs são registros formais de decisões arquiteturais. Este Skill automatiza a criação e a manutenção de ADRs em formato Markdown padronizado, garantindo rastreabilidade, consistência de estrutura e compatibilidade com Obsidian.

Core Features & Use Cases

Criar novos ADRs com o código ADR-{NNN} e o título descritivo no formato ADR-{NNN}_{slug}.md.
Atualizar ADRs existentes a partir do código (ex.: ADR-001) mantendo a forma e o front matter exigidos.
Garantir links internos no estilo wikilink do Obsidian e um front matter completo para facilitar indexação e governança.
Suportar a inclusão de informações adicionais de contexto, decisão, alternativas e riscos dentro de uma estrutura padronizada.

Quick Start

Crie um novo ADR com o código ADR-001 e o título descritivo no formato ADR-001_{slug}.md.

Frequently Asked Questions about adr-writer

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

FAQPage Schema

How do I create Architecture Decision Records in Markdown with a standardized format?▼

Architecture Decision Records in Markdown require a standardized structure enforcing file naming like ADR-{NNN}_{slug}.md, complete front matter schemas, and Obsidian wikilinks to ensure traceability and proper indexing within your knowledge base.

What is an Architecture Decision Record and when should I document one?▼

An Architecture Decision Record (ADR) is a formal log capturing architectural decisions. You should document an ADR whenever you make a significant architectural choice, recording the context, decision, alternatives, and risks to maintain project governance and traceability.

Does this ADR generation approach work with Obsidian wikilinks and front matter?▼

Yes, this ADR generation approach works with Obsidian by enforcing Obsidian-style wikilinks for internal references and requiring a complete front matter schema. This integration ensures your decision records are fully indexed and navigable inside Obsidian.

How do I update existing ADRs while maintaining front matter and file naming conventions?▼

To update existing ADRs while maintaining conventions, you reference the specific code like ADR-001. The system applies updates while preserving the required ADR-{NNN}_{slug}.md file naming format and validating the complete front matter schema.

Can I save an Architecture Decision Record as a draft before publishing it?▼

Yes, you can save an Architecture Decision Record as a draft before publishing. The system supports both draft and published states in the front matter, allowing you to iteratively build context, decisions, and risks before final governance approval.

How are malformed or unsafe ADR contents handled during markdown generation?▼

Malformed or unsafe ADR contents are actively rejected during markdown generation. The system guards against unsafe inputs by validating the front matter schema and enforcing structural consistency, ensuring your architecture documentation remains secure and compliant.