skills.rest
UKGovernmentBEIS
UKGovernmentBEISOFFICIAL
Explore all skills by this author →
GitHub

write-an-adr

Write Architectural Decision Records documenting significant design choices in a numbered adr directory.

657|419|Updated Oct 2, 2024
Search Tags:#ADR#Markdown#Documentation#architecture decision record#design decisions#nygard format
One-click install
npx skills add https://github.com/UKGovernmentBEIS/inspect_evals --skill write-an-adr
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-an-adr
Source: https://github.com/UKGovernmentBEIS/inspect_evals/tree/main/.claude/skills/write-an-adr
Command: npx skills add https://github.com/UKGovernmentBEIS/inspect_evals --skill write-an-adr

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve?

Architectural decisions often go undocumented or get lost in PR discussions, leaving future team members unable to understand why a design choice was made. This Skill produces a properly formatted, sequentially numbered ADR file capturing the decision, its context, and its consequences.

Core Features & Use Cases

  • Sequential ADR numbering: Scans the existing adr/ directory, finds the highest number, and assigns the next zero-padded identifier (e.g., 0002).
  • Structured template: Uses the Nygard ADR format (Status, Context, Decision, Consequences) with optional Considered Options and Rationale sections, loaded from assets/adr-template.md.
  • Guided information gathering: Extracts decision details from design docs or PR discussions when available, or asks targeted clarifying questions.
  • Use Case: After deciding to host eval assets on HuggingFace Hub, ask the assistant to record the decision; it creates adr/0003-use-huggingface-for-assets.md with full context, alternatives considered, and consequences.

Quick Start

Ask the assistant to write an ADR documenting the decision to use HuggingFace Hub for asset hosting, including the alternatives considered.

Frequently Asked Questions about write-an-adr

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

FAQPage Schema
How do I write an Architectural Decision Record?▼

Describe the decision, its motivating context, alternatives considered, and expected consequences. The Skill assigns the next sequential number, applies the ADR template from assets/adr-template.md, and writes the file to adr/NNNN-slug.md for your review.

What format does an ADR use?▼

This workflow follows the Nygard ADR format with Status, Context, Decision, and Consequences sections, plus optional Considered Options and Rationale sections drawn from MADR. Each ADR captures exactly one architecturally significant decision.

How are ADR numbers and filenames assigned?▼

The Skill lists files in the adr/ directory, finds the highest existing number, and increments it by one, zero-padded to four digits. The filename combines the number with a short kebab-case slug, such as adr/0002-use-huggingface-for-assets.md.

Can I update an ADR after it has been accepted?▼

Accepted ADRs are treated as immutable and should not be edited to reflect new information. Instead, write a new ADR that supersedes the old one, adding a Supersedes link in the new record and a Superseded by line in the old one.

What status values can an ADR have?▼

An ADR status is one of Proposed, Accepted, Rejected, Deprecated, or Superseded, defaulting to Proposed. The typical lifecycle moves from Proposed to Accepted or Rejected, and later to Deprecated or Superseded.

Related Skills

Explore More Software Engineering Skills→
anthropicsanthropics
23.4k

architecture

Create and evaluate Architecture Decision Records for system design choices.

Official
Intermediate
c-tomiokac-tomioka

adr-madr

Generate MADR-compliant architectural decision records from git logs, pull requests, or freeform text.

Community
Intermediate
abudhahirabudhahir

architecture-documenter

Generate system architecture documentation and Architecture Decision Records.

Community
Advanced
Claude-Code-Community-IrelandClaude-Code-Community-Ireland
10

architecture-decision-records

Create and manage Architecture Decision Records in multiple formats.

Official
Intermediate