adr-architecture — Claude Code skill: writes ADRs with trade-offs
adr-architecture turns an architecture choice into a written decision record with context, rejected options and consequences, then scores the draft against a rubric.
no license 118 installs ★ 203 updated 2026-09-01
npx skills add lyndonkl/claude --skill adr-architecture -a claude-codeWhat adr-architecture does
The skill runs a five-step workflow. It starts by pulling the decision context: who decides, what constraints and requirements apply. Then it picks a template, writes adr-{number}-{short-title}.md, checks the draft against a rubric and suggests a home in docs/adr/ or architecture/decisions/.
Resources ship with it: resources/template.md for technology choices, resources/methodology.md for decisions where several choices depend on each other, and three worked examples covering a database pick, a move to microservices and API versioning. Each record holds context, the decision itself, the alternatives weighed, consequences and a status.
Quality is scored with resources/evaluators/rubric_adr_architecture.json. The floor is 3.5, and the skill tells you to aim for 4.5 when a decision is contested. Old records stay untouched: status may change, the text does not, and a replacement gets its own file that links back.
What it helps with
- Record why PostgreSQL won over MySQL
- Write up a microservices migration with its rollback plan
- Document an API versioning standard and its exceptions
- Supersede an outdated decision without losing the trail
- Score a draft against the rubric before review
Example prompts for the agent
- Draft an ADR for picking Postgres as our primary database, with the alternatives we rejected
- Write the ADR for our microservices move using
resources/methodology.mdand file it underdocs/adr/ - Review
adr-012-api-versioning.mdagainst the rubric and list what's missing
How to install adr-architecture
1Skills CLI (Vercel)
npx skills add lyndonkl/claude --skill adr-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/adr-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/adr-architecture/
1Skills CLI (Vercel)
npx skills add lyndonkl/claude --skill adr-architecture -a codex2Manually: put the files in place
.agents/skills/adr-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add lyndonkl/claude --skill adr-architecture -a cursor2Manually: put the files in place
.cursor/skills/adr-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install lyndonkl/claude skills/adr-architecture2Manually: put the files in place
.github/skills/adr-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add lyndonkl/claude --skill adr-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/lyndonkl/claude --path skills/adr-architectureManually: put the files in place
.devin/skills/adr-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add lyndonkl/claude --skill adr-architecture -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-architecture
How do I install adr-architecture in Claude Code?
Run npx skills add lyndonkl/claude --skill adr-architecture -a claude-code. The skill file lands at ~/.claude/skills/adr-architecture/SKILL.md.
What does adr-architecture do?
It helps produce an architecture decision record: gathers context, states the decision, the alternatives and the consequences, then checks the text against a rubric.
Can I edit an ADR after it's accepted?
Records stay immutable. Change the status and write a new ADR that points at the old one instead of rewriting it.