skills.rest
iyaki
iyakiCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

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
One-click install
npx skills add https://github.com/iyaki/opencode-base-template --skill adr-skill-iyaki
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
telum-aitelum-ai
2

project-import

Create a Speck project structure with a skeleton project.md file.

Official
Basic
jmanhypejmanhype
24

spec-kit-workflow

Implement Spec Kit workflow phases and generate project artifacts.

Community
Basic
stevolandstevoland

adr

Create and manage MADR-compliant Architecture Decision Records across projects.

Community
Basic
zzafergokzzafergok
1

markdown-to-html-skill

Convert Markdown documents to HTML using marked.js, pandoc, gomarkdown, or static site generators.

Community
Intermediate