Create Architectural Decision Record

From the author

Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.

— the description by PlagueHO

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill automates the creation of Architectural Decision Records (ADRs) by transforming user-provided context, decisions, and alternatives into a standardized, professional markdown format. It enforces a rigorous structure that includes front matter, status tracking, consequence analysis, and rejection rationales, ensuring that technical decisions are documented with both human readability and machine-parsing capabilities in mind.

What it does

Generates standardized ADR markdown files with YAML front matter.
Structures documentation to include context, decision rationale, and consequences.
Categorizes positive and negative outcomes using coded bullet points.
Documents alternative options and the specific reasons for their rejection.
Provides a template for implementation notes and external references.
Validates required inputs before generating the final document.

When to use it

When you need to formalize a significant technical or architectural decision.
When you want to ensure consistent documentation standards across a development team.
When you need to track the evolution of system architecture over time.
When you need to provide clear rationales for rejected technical alternatives.

Advantages

Ensures architectural decisions are documented with high clarity and consistency.
Facilitates easier onboarding for new team members by providing historical context.
Supports machine-parsing for automated documentation or knowledge management systems.
Forces explicit consideration of trade-offs and negative consequences.

Usage examples

“Create an ADR for choosing PostgreSQL over MongoDB for our new user service.”: The agent generates a structured ADR file detailing the context of the user service, the decision to use PostgreSQL, the trade-offs involved, and the reasons for rejecting MongoDB.
“Document our decision to implement a microservices architecture for the billing module.”: The agent produces a formal ADR document including the architectural principles, potential risks, and implementation notes required for the transition.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/github/create-architectural-decision-record/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip create-architectural-decision-record.zip -d .agents/skills

Documentation by PlagueHO

Create an ADR document for ${input:DecisionTitle} using structured formatting optimized for AI consumption and human readability.

Inputs

Context: ${input:Context}
Decision: ${input:Decision}
Alternatives: ${input:Alternatives}
Stakeholders: ${input:Stakeholders}

Input Validation

If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide the missing information before proceeding with ADR generation.

Requirements

Use precise, unambiguous language
Follow standardized ADR format with front matter
Include both positive and negative consequences
Document alternatives with rejection rationale
Structure for machine parsing and human reference
Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections

The ADR must be saved in the /docs/adr/ directory using the naming convention: adr-NNNN-[title-slug].md, where NNNN is the next sequential 4-digit number (e.g., adr-0001-database-selection.md).

Required Documentation Structure

The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:

---
title: "ADR-NNNN: [Decision Title]"
status: "Proposed"
date: "YYYY-MM-DD"
authors: "[Stakeholder Names/Roles]"
tags: ["architecture", "decision"]
supersedes: ""
superseded_by: ""
---

# ADR-NNNN: [Decision Title]

## Status

**Proposed** | Accepted | Rejected | Superseded | Deprecated

## Context

[Problem statement, technical constraints, business requirements, and environmental factors requiring this decision.]

## Decision

[Chosen solution with clear rationale for selection.]

## Consequences

### Positive

- **POS-001**: [Beneficial outcomes and advantages]
- **POS-002**: [Performance, maintainability, scalability improvements]
- **POS-003**: [Alignment with architectural principles]

### Negative

- **NEG-001**: [Trade-offs, limitations, drawbacks]
- **NEG-002**: [Technical debt or complexity introduced]
- **NEG-003**: [Risks and future challenges]

## Alternatives Considered

### [Alternative 1 Name]

- **ALT-001**: **Description**: [Brief technical description]
- **ALT-002**: **Rejection Reason**: [Why this option was not selected]

### [Alternative 2 Name]

- **ALT-003**: **Description**: [Brief technical description]
- **ALT-004**: **Rejection Reason**: [Why this option was not selected]

## Implementation Notes

- **IMP-001**: [Key implementation considerations]
- **IMP-002**: [Migration or rollout strategy if applicable]
- **IMP-003**: [Monitoring and success criteria]

## References

- **REF-001**: [Related ADRs]
- **REF-002**: [External documentation]
- **REF-003**: [Standards or frameworks referenced]

Files

ATTRIBUTION.mdAdded by AutoGineer1.2 KiB
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md3.0 KiB

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Setup TS Deep Modules
Matt Pocock· Community
Configures dependency-cruiser to enforce deep module boundaries in TypeScript repositories.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskHas scriptsGitHub stars of the source repository317.5k
To Spec
Matt Pocock· Community
Synthesizes conversation context into a structured technical specification and publishes it to a project issue tracker.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Improve Codebase Architecture
Matt Pocock· Community
A systematic process to identify, visualize, and refine architectural deepening opportunities in a codebase.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Domain Modeling
Matt Pocock· Community
An expert assistant for defining project terminology, maintaining a glossary, and documenting architectural decisions.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Codebase Design
Matt Pocock· Community
A shared vocabulary and set of principles for designing deep, testable, and maintainable software modules.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Prototype
Matt Pocock· Community
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k