adr-drafting

Draft new Architecture Decision Records as standards-compliant Markdown files.

Updated Sep 10, 2025
One-click install
npx skills add https://github.com/tillysoso/mv1 --skill adr-drafting
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: adr-drafting
Source: https://github.com/tillysoso/mv1/tree/main/.claude/skills/adr-drafting
Command: npx skills add https://github.com/tillysoso/mv1 --skill adr-drafting

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Creates new Architecture Decision Record (ADR) documents for significant architectural changes using a consistent template and repository-aware naming and storage guidance. Use when a user or agent decides on an architectural change, needs to document technical rationale, or wants to add a new ADR to the project history.

Core Features & Use Cases

  • ADR drafting: from discovery to final Markdown using standard sections.
  • Conventions discovery: inspects repository for ADR location and naming patterns, or defaults to docs/architecture/adr with zero-padded filenames like 0001-<title>.md.
  • Guided workflow: prompts for Title, Status, Context, Decision, and Consequences, and ensures you are creating a new ADR (not editing an existing one).
  • Use Case: Document major architectural decisions to preserve history and rationale.

Quick Start

Provide the ADR details (title, context, decision, and consequences) and let the skill draft and save a new ADR file in the repository’s ADR location.

Frequently Asked Questions about adr-drafting

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

FAQPage Schema
How do I document architectural decisions and rationale in a repository?

Use an Architecture Decision Record (ADR) to document architectural decisions by capturing context, rationale, and trade-offs. This skill generates a standards-compliant Markdown file using standard sections like title, status, context, decision, and consequences.

What is an Architecture Decision Record and when do I need to create one?

An Architecture Decision Record (ADR) is a document capturing significant architectural changes and their technical rationale. You need to create one when making a significant architectural change, documenting constraints, or adding to project history.

How to generate a new ADR Markdown file with the correct naming conventions?

Generate a new ADR Markdown file by providing the title, context, decision, and consequences. The skill enforces ADR conventions by inspecting the repository for existing patterns or defaulting to zero-padded filenames like 0001-title.md in the architecture directory.

Can I use this to edit an existing Architecture Decision Record?

No, this skill is designed exclusively for drafting new Architecture Decision Records. It ensures you are creating a new ADR rather than editing an existing one, guiding you through a workflow to capture title, status, context, decision, and consequences.

What sections are required when writing an Architecture Decision Record?

Writing an Architecture Decision Record requires standard sections including title, status, context, decision, and consequences. The guided workflow prompts for these specific inputs to ensure the final Markdown file captures the full rationale and trade-offs.