adr

Creates and manages structured Architecture Decision Records with automatic numbering and filing.

Updated Apr 13, 2026
One-click install
npx skills add https://github.com/nille/shipkit --skill adr-nille
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: adr
Source: https://github.com/nille/shipkit/tree/main/shipkit/core/skills/adr
Command: npx skills add https://github.com/nille/shipkit --skill adr-nille

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Architectural decisions often lack context and rationale, leading to confusion and rework when team members join or revisit code.

Core Features & Use Cases

  • Create structured ADRs with a title, status, context, decision, and consequences
  • Determine storage location (docs/adr, docs/decisions, adr/, or knowledge directories), auto-numbering, and linking related ADRs
  • Support superseding, re-use, and auditing of decision history across projects

Quick Start

Draft an ADR for the decision to adopt a new logging framework in the next release.

Frequently Asked Questions about adr

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

FAQPage Schema
What is an Architectural Decision Record and when do I need one?

To draft an Architectural Decision Record, create a structured document containing a title, status, context, decision, and consequences. The system auto-discovers storage locations like docs/adr and applies versioned numbering for tracking.

Can I supersede an old architectural decision when requirements change?

Yes, you can supersede old architectural decisions. The system enforces superseding conventions and supports linking related ADRs, ensuring that re-use and auditing of your decision history remain accurate across projects.

What is the best way to manage architectural documentation across multiple projects?

The best way to manage architectural documentation is using structured ADRs with automatic location discovery and versioned numbering. This enforces a consistent format and maintains a clear, auditable history of decisions across multiple projects.

How do I structure an ADR to include context and consequences?

Structure your ADR using the enforced format: title, status, context, decision, and consequences. This captures the problem space clearly and ensures the rationale and impact of your software architecture decisions are fully documented.

Do I need a specific directory structure to store architectural decision records?

No specific directory structure is strictly required, as the system features automatic location discovery. It identifies standard storage paths like docs/adr, docs/decisions, adr/, or knowledge directories to save your records.