adr — Claude Code skill: what it does, how to install
Guides creation and review of Architecture Decision Records using MADR templates and Olaf Zimmermann's criteria.
no license 146 installs ★ 54 updated 2026-02-26
npx skills add ncklrs/startup-os-skills --skill adr -a claude-codeWhat adr 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.
What it helps with
- 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 for the agent
- Run
adr check-readyto see if we have enough context to choose our database - Output a blank decision layout using
adr template - Audit
docs/adr/0002-auth.mdwithadr review
How to install adr
1Skills CLI (Vercel)
npx skills add ncklrs/startup-os-skills --skill adr -a claude-code2Manually: put the files in place
~/.claude/skills/adr/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/adr/
1Skills CLI (Vercel)
npx skills add ncklrs/startup-os-skills --skill adr -a codex2Manually: put the files in place
.agents/skills/adr/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ncklrs/startup-os-skills --skill adr -a cursor2Manually: put the files in place
.cursor/skills/adr/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ncklrs/startup-os-skills skills/adr2Manually: put the files in place
.github/skills/adr/SKILL.md1Skills CLI (Vercel)
npx skills add ncklrs/startup-os-skills --skill adr -a gemini-cli2Platform CLI
gemini skills install https://github.com/ncklrs/startup-os-skills --path skills/adrManually: put the files in place
.devin/skills/adr/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ncklrs/startup-os-skills --skill adr -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about adr
How to install adr in Claude Code?
Run npx skills add ncklrs/startup-os-skills --skill adr -a claude-code. The definition gets placed into ~/.claude/skills/adr/SKILL.md.
What does the adr skill do?
It assists developers in drafting, evaluating, and cataloging architectural choices. It provides structured MADR formats and tests decisions against research-backed quality criteria.
What does the ECADR criteria check?
ECADR serves as a definition of done: it verifies evidence, comparative criteria for options, stakeholder consensus, shared documentation, and an active review plan.