skills.rest
miyake-san
miyake-sanCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

adr-skill

Create and maintain Architecture Decision Records with implementation plans for coding agents.

Updated Aug 28, 2026
Search Tags:#documentation#codebase#adr#agent workflow#decision tracking#madr#architecture decision records
One-click install
npx skills add https://github.com/miyake-san/sogo-agent-platform --skill adr-skill-miyake-san
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr-skill
Source: https://github.com/miyake-san/sogo-agent-platform/tree/main/skills/core/adr-skill
Command: npx skills add https://github.com/miyake-san/sogo-agent-platform --skill adr-skill-miyake-san

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Architecture decisions are often made implicitly through code and conversations, leaving no record of why choices were made. This Skill captures decisions as self-contained ADRs that both humans and coding agents can act on without follow-up questions. ## Core Features & Use Cases - Four-Phase ADR Workflow: Scans the codebase for existing ADRs and tech stack, interviews the human with Socratic questions, drafts from simple or MADR templates, and reviews against an agent-readiness checklist. - Lifecycle Management: Create, accept, reject, deprecate, or supersede ADRs, bootstrap an ADR directory with an index, and keep code linked to decisions via comments. - Agent-First Implementation Plans: Every ADR includes affected paths, dependencies, patterns to follow or avoid, and testable verification checkboxes. - Use Case: An agent about to introduce a new database dependency stops, proposes an ADR, interviews the developer, and produces a dated record in docs/decisions/ with an implementation plan the next agent can execute directly. ## Quick Start Ask the agent to create an ADR for the decision to adopt PostgreSQL for the production database, including an implementation plan and verification criteria.

Frequently Asked Questions about adr-skill

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

FAQPage Schema
How do I create an Architecture Decision Record for my project?▼

Run the new_adr.js script with a title, or follow the four-phase workflow: scan the codebase for existing ADRs, capture intent through Socratic questions, draft from a simple or MADR template, then review against the agent-readiness checklist before finalizing.

When should I write an ADR versus skipping it?▼

Write an ADR when a decision changes how the system is built, is hard to reverse, affects other contributors, or has real alternatives. Skip it for routine implementation choices, bug fixes, style preferences, or decisions already captured in an existing ADR.

What is the difference between the simple and MADR ADR templates?▼

The simple template suits straightforward decisions with one clear winner and minimal tradeoffs. The MADR template fits decisions with three or more real options, structured pros and cons, explicit decision drivers, and cross-team stakeholder review.

How do I change an ADR status from proposed to accepted?▼

Use the set_adr_status.js script with the ADR file path and the new status value. It updates YAML front matter, bullet-style status lines, or Nygard-style Status sections in place, and supports JSON output for automation.

Can I bootstrap ADRs in a repo that has none?▼

Yes. Run bootstrap_adr.js to create the ADR directory, an index README, and a filled-out first ADR titled Adopt architecture decision records. Use --dir to override the directory and --json for machine-readable output.

Related Skills

Explore More Software Engineering Skills→
compozycompozy
2.5k

cy-create-techspec

Generates a complete draft of TechSpec and companion documents from your uploaded files.

Official
Advanced
supermalangsupermalang

qa-tester

Verify active task acceptance criteria and record QA sign-off in docs/ROADMAP.md.

Community
Advanced
jimuttjimutt
4

dld-audit-auto

Audit code annotations against decision records and open a pull request with fixes.

Community
Advanced
ACGSpgpACGSpgp

architecture-decision-records

Create and manage Architecture Decision Records with lifecycle tracking.

Official
Intermediate