Agent skill · writing content · vercel
adr-skill
Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.
Why this skill is useful
Provides a structured framework for creating ADRs that ensures agents can implement decisions without ambiguity, including specific implementation plans and constraints.
What it needs
About 10k tokens when loaded. Last updated 2026-08-07. 26,057 stars on the source repository.
What this skill does
ADR Skill Philosophy ADRs created with this skill are executable specifications for coding agents. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions. This means: Constraints must be explicit and measurable, not vibes Decisions must be specific enough to act on ("use PostgreSQL 16 with pgvector" not "use a database") Consequences must map to concrete follow-up tasks Non-goals must be stated to prevent scope creep The ADR must be self-contained — no tribal knowledge assumptions The ADR must include an implementation plan — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly When to Write an ADR Write an ADR when a decision: Changes how the system is built or operated (new dependency, architecture pattern, infrastructure choice, API design) Is hard to reverse once code is written against it Affects other people or agents who will work in this codebase later Has real alternatives that were considered and rejected Do NOT write an ADR for: Routine implementation choices within an established pattern Bug fixes or typo corrections Decisions already captured in an existing ADR (update it instead) Style preferences already covered by linters or formatters When in doubt: if a future agent working in this codebase would benefit from knowing why this choice was made, write the ADR. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills vercel/adr-skill