Adr Review Agent Skill
>- Review one or more ADRs with fresh eyes (as a team member without prior context), identify narrative and structural issues, then rewrite them. Use when the user asks to review, improve, rewrite, or take a fresh-eyes pass on an ADR or a set of ADRs (Architecture Decision Records).
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/prisma/prisma --skill adr-reviewThe instruction itself
5 sections, as written by the authorReviewing and Rewriting ADRs
Read each ADR with fresh eyes. Pretend you're a member of the team who doesn't have all the context the author has. The goal is to find places where the document assumes context the reader doesn't have, buries the decision, or carries baggage that won't make sense to a future reader.
This skill applies whether you're working on a single ADR or a batch. Treat each ADR independently — do the analysis and rewrite per document — even when several are in scope at once.
Workflow
- Analyze first, in chat. Before touching any file, list the issues you found and explain them. Do not rewrite silently. When multiple ADRs are in scope, group your analysis per ADR so the user can react to each one before rewrites land.
- Then rewrite each document to address the issues you identified.
What a good ADR looks like
- Starts with a clear grounding example. Give the reader something concrete to pin understanding to before the abstract reasoning starts.
- Has a strong narrative that builds the topic up bit by bit, explaining clearly throughout. Don't compress; let ideas breathe.
- Leads with the decision. State what's being decided up front. The reader should know the conclusion before working through the reasoning.
- Ends with alternatives considered. Put rejected options last so the reader isn't loaded down with information about paths the document is making irrelevant.
What an ADR must NOT contain
ADRs are long-lived documentation. They should not contain:
- References to Linear tickets, GitHub issues, or other ticket trackers.
- Milestones from the project that produced the ADR.
- States the system passed through during or preceding a refactor that will never be seen again — interim names, deprecated wrappers being removed, "current" qualifiers, "we used to" framing.
If a piece of context only makes sense to someone who lived through the change, cut it or rewrite it as a fact about the system as it is.
Output shape
When invoked:
- Read the ADR (or ADRs) in scope.
- Write your analysis in the chat — what's missing, what's buried, what's transient, what's unclear to a fresh reader. Be specific; quote or cite the parts you're flagging. For multiple ADRs, label each block clearly.
- Then rewrite each file end-to-end so it follows the structure above.
Other skills for the same job
different authors, same section of the catalogue
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Reduces cognitive load and keeps your digital workspace tidy without manual effort.
Generates creative domain name ideas for your project and checks availability across multiple TLDs (.com, .io, .dev, .ai, etc.). Saves hours of brainstorming and manual checking.
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
Creative research ideation and exploration. Use for open-ended brainstorming sessions, exploring interdisciplinary connections, challenging assumptions, or identifying research gaps. Best for early-stage research planning when you do not have specific observations yet. For formulating testable hypotheses from data use hypothesis-generation.
Comprehensive GitHub project management with swarm-coordinated issue tracking, project board automation, and sprint planning
Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
How to use it
Take prisma/adr-review from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.