Guide · Agent skill
How to use the ADR Review and Rewrite agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The adr-review skill is an agent skill that tells an AI agent to read Architecture Decision Records (ADRs), the short documents explaining why a team made a technical choice, as if it were a new team member with no background. This guide is for engineering leads, teams cleaning up old ADRs, and authors who want a review before publishing. By the end you will know how to install the skill, how to ask for a review in plain language, and what to check in the output.
ADR Review and Rewriteprisma/orm · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the adr-review ZIP file from this page.
- 2Unzip the skill. Unzip the file so the skill folder contains SKILL.md.
- 3Place the folder. Put it in ~/.claude/skills/ for personal use or in your project's .claude/skills/ folder for one project.
- 4Or upload it in the apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 5Ask for a review. Name the ADR file or folder and ask for a fresh-eyes review or rewrite.
- 6Check the analysis. Read the issues the agent lists in chat before accepting any rewrite.
- 7Verify the rewrite. Compare the rewritten file with the original and confirm no needed history was removed.
What agent skills are and what this one does
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This one is named adr-review and is a writing and editing aid. It does not change how the software itself works.
When triggered, the agent reads each ADR in scope and looks for places where the document assumes context the reader lacks, buries the decision, or carries baggage that will confuse a future reader.
- Flags missing context and assumptions a newcomer would not have.
- Flags decisions that are buried instead of stated up front.
- Flags temporary details, such as interim names, deprecated wrappers and "we used to" framing, that will not make sense later.
- Rewrites the document so it starts with a grounding example, leads with the decision, and ends with rejected alternatives.
Install the adr-review skill
Download the ZIP file from this page and unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
You can also upload the skill in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload it there.
- Personal install: ~/.claude/skills/
- Project install: the .claude/skills/ folder inside your project
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with a natural request
The skill's description says it applies when you ask to review, improve, rewrite, or take a fresh-eyes pass on an ADR or a set of ADRs. You do not need to name the skill. Point the agent at the file or files and describe what you want.
- "Review docs/adr/0007-use-postgres.md with fresh eyes and tell me what confuses a new engineer."
- "Take a fresh-eyes pass on all the ADRs in docs/decisions/ written during the auth refactor."
- "Improve this ADR so the decision comes first and the rejected options come last."
Review the analysis before accepting rewrites
The skill asks the agent to analyse first and rewrite second. The agent lists its issues in chat before touching any file, so you can react before changes land. When several ADRs are in scope, the analysis is grouped per ADR, and each document is treated independently.
Check the rewritten output carefully. The skill tells the agent to remove project-specific context, and a rewrite can drop history your team still needs.
- Read the chat analysis and reply if you disagree with any flagged issue.
- Compare each rewrite against the original before accepting it.
- Confirm no history that your team still needs has been removed.
Know what the skill needs and what it does not do
The skill file lists no requirements. It does not run scripts and does not use the network. The only file in the package is SKILL.md.
- Requirements: none listed
- Runs scripts: no
- Uses network: no
- Files: SKILL.md
Tips for getting good results
Ask for one ADR at a time when the documents are long or important, so each analysis is easier to check. For a backlog, ask for batches and review each group's analysis before moving on.
The skill is aimed at readers who lack context, so it works best on ADRs that are meant to outlive the project that produced them.
- Start with a single ADR to see the style of analysis before running a batch.
- Keep a copy of the original files so you can compare.
- Use it before publishing a new ADR for a fresh-eyes check.
What people use it for
- Cleaning up a backlog of ADRs written during a refactor.
- Giving newcomers an easier-to-follow version of an existing decision record.
- Getting a fresh-eyes pass on a new ADR before it is published.
- Checking that a long ADR states its decision before the reasoning.
Frequently asked questions
Is the adr-review skill free?
The source file does not state a price or licence terms for the skill in the body text. The listing shows the licence as Apache-2.0, so check that licence yourself before reuse. The skill itself runs as a text file with no scripts.
What do I need to install the adr-review skill?
The listing states no requirements. Download the ZIP, unzip it, and place the folder in ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
Does the adr-review skill run scripts or use the internet?
No. The listing says it runs no scripts and uses no network. The package contains only SKILL.md.
Will the skill change my software?
No. It is a writing and editing aid for ADR documents and does not change how the software works.
Can the rewrite delete important information?
It can. The skill tells the agent to remove project-specific context, so review the output and confirm that history your team still needs is kept before accepting it.
Do I need to know the skill name to use it?
No. Ask the agent in plain language to review, improve, rewrite or take a fresh-eyes pass on an ADR, and the skill's description will match the request.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use adr-review if you maintain architecture decision records that newcomers struggle with, or if you want a fresh-eyes check before publishing one. Skip it if your project does not keep ADRs, or if you need every piece of project history preserved exactly, since the skill is designed to remove project-specific context.
Download the skill