adr-skill

Generate and organize Architecture Decision Records with MADR-compatible templates.

Updated Sep 25, 2025

Search Tags:#automation #architecture #documentation #codebase #adr #madr #agent-workflows

Ready to run

npx skills add https://github.com/iyaki/opencode-base-template --skill adr-skill-iyaki

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: adr-skill
Source: https://github.com/iyaki/opencode-base-template/tree/main/.agents/skills/adr-skill
Command: npx skills add https://github.com/iyaki/opencode-base-template --skill adr-skill-iyaki

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Architecture decisions often live only in conversations and code comments, making it hard for new contributors (humans or agents) to understand why a codebase arrived at its current design. The ADR skill provides a structured, version-controlled way to capture, justify, and propagate decisions about system architecture.

Core Features & Use Cases

Bootstrap an ADR directory and index to centralize decisions.
Create, update, or supersede Architecture Decision Records using MADR-compatible templates.
Enforce ADR conventions and provide a blueprint for agents to implement decisions with an explicit implementation plan and verification criteria in a machine-friendly format.
Use Socratic questioning to surface intent before drafting an ADR and ensure outputs are agent-ready.

Quick Start

Draft an ADR that documents the decision and use the ADR tooling to generate it and update the index.

Frequently Asked Questions about adr-skill

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

FAQPage Schema

How do I document architecture decisions in a codebase for AI agents?▼

Architecture Decision Records provide a version-controlled way to capture and justify system design choices, ensuring new contributors understand why a codebase arrived at its current design instead of relying on scattered conversations and code comments.

How do I bootstrap an ADR directory and index for an existing repository?▼

The ADR tooling enforces conventions by providing an explicit implementation plan and verification checklist, ensuring outputs are agent-ready and guiding both automation and human review of architecture decisions.

What is the best way to supersede an old Architecture Decision Record?▼

The best way to supersede an old ADR is to use a structured tool that updates the centralized decision log and links the superseded record to the new ADR, maintaining a clear historical lineage of architecture decisions.

Does ADR tooling support agentic coding workflows and automation?▼

Yes, ADR tooling supports agentic coding workflows by using Socratic questioning to surface intent before drafting, generating machine-friendly formats with explicit implementation plans and verification criteria for AI agents to execute.