skills.rest
sd0xdev
sd0xdevCOMMUNITY
Explore all skills by this author →
𝕏@Develop0xGitHub

adr

Writes numbered Architecture Decision Records with superseded linking into feature documentation directories.

189|25|Updated Jan 30, 2026
Search Tags:#documentation#markdown#adr#decision tracking#architecture decision record#superseded#numbering
One-click install
npx skills add https://github.com/sd0xdev/sd0x-harness --skill adr-sd0xdev
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr
Source: https://github.com/sd0xdev/sd0x-harness/tree/main/skills/adr
Command: npx skills add https://github.com/sd0xdev/sd0x-harness --skill adr-sd0xdev

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Architectural decisions get re-litigated when the reasoning behind them is never recorded. This Skill writes a properly numbered, consistently formatted Architecture Decision Record (ADR) into a feature's docs directory so the decision, its context, and its tradeoffs are preserved. ## Core Features & Use Cases - Automatic numbering: Scans both the feature root and its archived/ subdirectory for existing adr-*.md files and assigns the next numeric max, zero-padded to three digits (adr-001, adr-002, ...). - Superseded handling: When a new ADR replaces an old one, it edits both files in the same pass — the new ADR gets a Supersedes link and the old ADR's Status flips to Superseded with a back-link. - Classification guard: Validates the generated filename against the doc taxonomy before writing, so titles containing words like runbook or checklist don't silently misclassify the file. - Use Case: After choosing JWT over session cookies for the auth feature, run the skill to produce docs/features/auth/adr-001-use-jwt-over-session-cookies.md with Context, Decision, Status, Consequences, and Alternatives sections. ## Quick Start Ask the AI to write an ADR for the auth feature recording the decision to use JWT over session cookies.

Frequently Asked Questions about adr

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

FAQPage Schema
How do I write an Architecture Decision Record for a feature?▼

Invoke the skill with the feature key and a title, then supply Context, Decision, Status, Consequences, and Alternatives. It writes docs/features/<feature>/adr-<NNN>-<title>.md using the bundled template, with the number computed automatically.

How is the ADR number calculated?▼

The next-adr-number.js script scans both the feature root and its archived/ subdirectory for files matching adr-<digits>-, takes the numeric maximum, and returns max plus one zero-padded to three digits. The first ADR in a feature becomes adr-001.

How do I mark an old ADR as superseded by a new one?▼

State that the new ADR supersedes an existing one when gathering content. The skill adds a Supersedes link to the new ADR and, in the same pass, flips the old ADR's Status to Superseded with a Superseded-by link back, using relative paths based on where the old file lives.

When should I not use an ADR?▼

Do not use an ADR for feature-wide technical design (use a tech spec), task progress tracking (use a request tracker), or bulk backfilling of historical decisions. The skill writes exactly one ADR per invocation.

Why would an ADR filename be rejected before writing?▼

Titles containing words like runbook or checklist, or ending in -fp-brief or -tech-brief, collide with other doc-taxonomy patterns and would misclassify the file. The skill asks you to rephrase the title, up to three attempts before escalating.

Related Skills

Explore More Software Engineering Skills→
DayoptDayopt

docs

Generate technical documentation and ADRs from feature descriptions.

Official
Intermediate
hcrosshcross
3

doc-writer

Generate ADRs, READMEs, and docstrings aligned with code changes.

Community
Intermediate
hodinhtuankiethodinhtuankiet

documentation-and-adrs

Document architecture decisions in ADRs under docs/decisions with sequential numbering.

Community
Advanced
jomcgijomcgi
5

adr

Create and manage Architecture Decision Records with status tracking.

Community
Advanced