# adr

Guides creation and review of Architecture Decision Records using MADR templates and Olaf Zimmermann's criteria.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 146 installs · ★ 54 repo stars
- Author: ncklrs
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ncklrs/startup-os-skills/tree/HEAD/skills/adr/SKILL.md
- Updated: 2026-02-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/adr

## What it does

This skill guides teams through the entire lifecycle of Architecture Decision Records (ADRs). It checks decision readiness against the START framework, drafts documents using MADR structure, and detects 11 common writing anti-patterns. Acceptance relies on the ECADR criteria to ensure evidence and review plans exist before marking decisions as final.

Interaction runs through explicit flags: `create` walks through questions step-by-step, `review` audits existing files, `check-ready` and `check-done` validate stage criteria, while `template` outputs clean Markdown. If a decision lacks high business impact or cross-component effects, the built-in significance test flags it early so you avoid documenting routine technical tasks.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ncklrs/startup-os-skills --skill adr -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/adr/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/adr/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ncklrs/startup-os-skills --skill adr -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/adr/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ncklrs/startup-os-skills --skill adr -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/adr/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ncklrs/startup-os-skills skills/adr
```

2. **Manually: put the files in place**
- File: `.github/skills/adr/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ncklrs/startup-os-skills --skill adr -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ncklrs/startup-os-skills --path skills/adr
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/adr/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add ncklrs/startup-os-skills --skill adr -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ncklrs/startup-os-skills/tree/HEAD/skills/adr/SKILL.md

## When to use it
- draft structured decision records using MADR markdown format
- verify decision readiness against five START checklist points
- audit existing ADR files for structural anti-patterns
- determine architectural significance before writing documentation

## Example prompts
- Run `adr check-ready` to see if we have enough context to choose our database
- Output a blank decision layout using `adr template`
- Audit `docs/adr/0002-auth.md` with `adr review`

## Similar
- [adr-writing](https://affpapa.org/en/nevibecode/skills/adr-writing.md) — skill · 254 installs
- [adr-standards](https://affpapa.org/en/nevibecode/rules/adr-standards.md) — rule · ★ 1627 repo stars
- [adr-drafting](https://affpapa.org/en/nevibecode/skills/adr-drafting.md) — skill · 3700 installs
- [030-architecture-adr-general](https://affpapa.org/en/nevibecode/skills/030-architecture-adr-general.md) — skill · 373 installs
- [adr-author](https://affpapa.org/en/nevibecode/skills/adr-author.md) — skill · ★ 1627 repo stars
- [create-adr](https://affpapa.org/en/nevibecode/skills/create-adr.md) — skill · ★ 7191 repo stars

From the same set: [ncklrs/startup-os-skills](https://affpapa.org/en/nevibecode/by/ncklrs/startup-os-skills.md) — 51 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
