Adr

Skill anmolnagpal/devops-skills/skills/adr

Multi-tool DevOps skills for Claude Code, Cursor, and Codex — Terraform, Kubernetes, Docker, GitHub Actions, GitLab CI, AWS FinOps, OWASP security.

Install

npx -y skills add anmolnagpal/devops-skills --skill adr

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

7 stars7 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Capture architectural decisions that have already been made, as structured ADRs (Architecture Decision Records). Use when user says 'record this decision', 'ADR this', 'why did we choose X', 'document this trade-off', 'we decided to...', or when a choice between alternatives has been settled and needs writing down. This records a decision; it does not make one. A question of the form 'should we use X or Y' is a design discussion, not an ADR request.

SKILL.md

4.0 KB, as published. Nobody here has run it

ADR Skill

Capture architectural decisions as they happen, so the why lives next to the code instead of in a Slack thread or someone's memory. Produces lightweight ADR documents under docs/adr/.

Keywords

adr, architecture decision record, decision, rationale, trade-off, alternatives, we decided, why did we choose, design decision, supersede, decision log, nygard

When to record a decision

The user says "record this", "ADR this", "let's document this decision".
A choice is made between significant alternatives: framework, library, database, language, pattern, API shape, infra/deploy approach, build vs buy.
The user says "we decided to…" or "the reason we're doing X instead of Y is…".
The user asks "why did we choose X?" → read and summarize the existing ADR.

For trivial or easily-reversible choices, don't create an ADR — note it inline and move on.

Output Artifacts

Request	Output
`/adr new "<title>"`	A new `docs/adr/NNNN-<slug>.md` + an updated index
`/adr list`	The decision log (ID, title, status, date)
`/adr supersede <NNNN>`	A new ADR marked as superseding an old one; old one flipped to `superseded`

Format

Lightweight Nygard ADR, adapted for AI-assisted work:

# ADR-NNNN: <Decision Title>

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: <who was involved>

## Context

What is the issue motivating this decision? The situation, constraints, and forces at
play. 2–5 sentences.

## Decision

What we are doing. 1–3 sentences, stated clearly.

## Alternatives Considered

### <Alternative>
- **Pros**: …
- **Cons**: …
- **Why not**: the specific reason it was rejected.

(Repeat per alternative.)

## Consequences

### Positive
- …

### Negative / trade-offs
- …

### Risks
- <risk and its mitigation>

NEW — Record a decision

Initialize once. If docs/adr/ does not exist, ask the user to confirm before creating it. On confirmation, create the directory, a README.md seeded with the index table header (below), and a template.md copy of the format above. Never create files without explicit consent.
Number it. Next zero-padded number after the highest existing docs/adr/NNNN-*.md (start at 0001). Slug = kebab-case of the title.
Fill it from the conversation — extract the decision, the context that prompted it, the alternatives actually weighed, and the consequences. Do not invent alternatives that were never discussed; if context is thin, ask one or two targeted questions.
Default status accepted when the user states a decision; proposed when still weighing. Date = today.
Update the index in docs/adr/README.md.

Index format

docs/adr/README.md:

# Architecture Decision Records

| ID | Title | Status | Date |
|----|-------|--------|------|
| [ADR-0001](0001-use-eks-over-ecs.md) | Use EKS over ECS | accepted | 2026-06-10 |

SUPERSEDE — Replace a decision

Read the old ADR.
Create a new ADR that references it: "Supersedes ADR-NNNN" in Context.
Flip the old ADR's Status to superseded by ADR-MMMM.
Update both rows in the index.

Never delete or rewrite a past ADR's decision — superseding preserves the history of why it changed, which is the whole point.