skills.rest
mattbutlerengineering
mattbutlerengineeringCOMMUNITY
Explore all skills by this author →
GitHub

new-adr

Scaffold sequential Architecture Decision Records in docs/adr/ with canonical format.

1|Updated Jan 24, 2026
Search Tags:#documentation#adr#scaffolding#architecture decisions#change management#engineering process#repository conventions
One-click install
npx skills add https://github.com/mattbutlerengineering/mattbutlerengineering --skill new-adr-mattbutlerengineering
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: new-adr
Source: https://github.com/mattbutlerengineering/mattbutlerengineering/tree/main/.claude/skills/new-adr
Command: npx skills add https://github.com/mattbutlerengineering/mattbutlerengineering --skill new-adr-mattbutlerengineering

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It removes the friction of creating new Architecture Decision Records by automatically finding the next available ADR number and generating an ADR file that matches your repository’s canonical docs/adr/ format.

Core Features & Use Cases

  • Sequential ADR scaffolding: Finds the next ADR index by scanning docs/adr/ADR-*.md, incrementing the highest ADR-NNN prefix, and handling duplicate numbers by applying a -b suffix when needed.
  • Consistent ADR structure: Creates docs/adr/ADR-NNN-<title>.md using your required template sections (Context, Decision, Consequences, Alternatives Considered) and date/name invariants.
  • Repository docs maintenance: Updates docs/adr/README.md by inserting the new ADR entry into the index table in numeric order.
  • Pre-commit compatibility: Reminds you that the pre-commit hook validates ADR format on commit, reducing formatting and convention drift.

Quick Start

Run the new-adr skill and answer the two prompts with a short kebab-case title and a one-sentence summary of the decision to generate the next ADR file and update the ADR index.

Frequently Asked Questions about new-adr

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

FAQPage Schema
How do I create a new Architecture Decision Record with the correct sequential numbering?▼

To create a new Architecture Decision Record, the skill scans existing ADR-NNN files in docs/adr/, increments the highest number, and generates a new ADR file with the next sequential identifier.

What sections are included in a standard architecture decision record template?▼

A standard architecture decision record template includes Context, Decision, Consequences, and Alternatives Considered sections, along with date and name invariants in the frontmatter.

How do I maintain the ADR index when adding new architecture decisions to a repository?▼

When adding new architecture decisions, the skill automatically updates docs/adr/README.md by inserting the new ADR entry into the index table in numeric order.

What happens if there are duplicate ADR numbers in the docs directory?▼

If duplicate ADR numbers exist in the docs directory, the skill handles the conflict by applying a -b suffix to the new ADR file identifier.

When do I need to record an architectural decision versus keeping implementation details?▼

You need to record an architectural decision when the outcome must be discovered by others, such as adding cross-cutting conventions or superseding prior ADRs, rather than remaining an implementation detail.

Does the ADR scaffolding process integrate with repository pre-commit hooks?▼

Yes, the ADR scaffolding process reminds you that a pre-commit hook validates the ADR format on commit, reducing formatting and convention drift.

Related Skills

Explore More Software Engineering Skills→
sortie-aisortie-ai
121

managing-adrs

Create and validate MADR 4.0 Architecture Decision Records with required frontmatter.

Official
Advanced
sunLeeesunLeee

check-commit-message

Validate Git commit messages against Conventional Commits rules.

Community
Intermediate
cody-hutsoncody-hutson

adr-helper

Creates Architecture Decision Records with unique numbers and prefilled metadata templates.

Community
Advanced
infantesromeroadrianinfantesromeroadrian

adr-new

Generate markdown Architecture Decision Records from a YAML template with sequential numbering.

Community
Intermediate