Adr Skill

Treats ADRs as executable specifications for coding agents, not just documentation for humans. The workflow forces you to scan existing decisions first, then walks through Socratic questioning to capture intent before drafting anything. What stands out is the "proactive trigger" list telling agents when to stop and propose an ADR mid-task, like before adding a new dependency or creating a new pattern. Ships with template variants and an agent-readiness checklist focused on implementation plans. Opinionated about structure but flexible on directory conventions. Use this when you want ADRs that actually help future agents implement decisions without twenty follow-up questions.

skills.sh installs: 3.5K
GitHub stars: 27.8K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add vercel/ai --skill adr-skill --agent claude-code

Installs into .claude/skills of the current project.

Files

ADR Skill

An ADR records what we decided and why. Keep it concise and self-contained so future contributors and coding agents can understand the decision without the original conversation. Implementation plans and verification belong in issues and pull requests.

When to Write an ADR

Write an ADR for decisions that change how the system is built or operated, have meaningful alternatives, and affect future work: architecture patterns, dependencies, infrastructure, or API design.

Routine implementation choices, bug fixes, and style preferences usually do not need an ADR. If a decision is already covered, update or reference the existing record.

When an architectural choice comes up during implementation, propose capturing it if its rationale would help future contributors. If the user did not explicitly ask you to write an ADR, confirm with them first before writing or editing one. Respect the user's requested scope.