Guide · Agent skill
How to use the Code Review (Standards and Spec) agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The code-review skill is an add-on for an AI coding agent that reviews the changes made since a commit, branch, or tag. It checks two things separately: whether the code follows your repo's written coding standards, and whether it does what the linked issue or spec asked for. This guide explains what the skill does, how to install it, how to ask for a review in plain language, and what it needs to run.
Code Review (Standards and Spec)mattpocock/skills · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip it so the code-review folder sits in ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the ZIP.
- 3Check git and the spec source. Make sure git is available in the repository and that you can reach the issue tracker or spec files if you want the Spec check.
- 4Ask for a review with a fixed point. Name the commit, branch, tag, or merge-base you want to compare against, for example review since main.
- 5Read the two reports. Review the Standards and Spec sections separately, following the cited rules and quoted spec lines.
- 6Act on the findings. Fix hard violations and missing requirements, and decide case by case on smell judgement calls.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a request matches the skill's description. The skill tells the agent how to carry out a specific kind of task.
This skill reviews the diff between HEAD and a fixed point you supply, such as a commit SHA, branch name, tag, main, or a merge-base. It runs two reviews in parallel sub-agents, each with a fresh context window, and then reports them side by side.
- Standards: does the code conform to the repo's documented coding standards (for example CODING_STANDARDS.md or CONTRIBUTING.md, if present)?
- Spec: does the code faithfully implement the originating issue or spec, and is there any behaviour that was not asked for?
- Smell baseline: the Standards review also flags common code smells, such as Mysterious Name or Duplicated Code, as labelled judgement calls rather than errors.
Install the code-review skill
Download the ZIP for this skill from this page and unzip it. The skill is made of agents/openai.yaml and SKILL.md. You can install it in one of two ways.
For Claude Code, unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/ (available across projects)
- Project install: .claude/skills/ inside the repository
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Prepare the repository and the spec
The skill reviews by reading the diff, so git must be available in the repository you are reviewing. Make sure the branch you want to review exists locally and that the fixed point you plan to use is reachable.
If you want the Spec check, the agent needs access to the issue tracker or the spec files. The skill looks for issue references in commit messages (such as Closes #45 or GitLab !67), a path you pass in, or a spec file under docs/, specs/, or .scratch/ that matches the branch name. If the tracker has not been set up, the skill tells you to run /setup-matt-pocock-skills.
- git must be available in the repository
- Access to the issue tracker or spec files is needed for the Spec check
- If no spec is found, the agent will ask you where it is; if you say there is none, the Spec review is skipped
Trigger the skill with natural requests
You do not need a special command. Ask for a review in plain language that names a fixed point. The skill is meant for requests to review a branch, a PR, work-in-progress changes, or phrases like review since X.
If you do not give a fixed point, the agent will ask for one. The agent first confirms the fixed point resolves and that the diff is not empty, so a bad ref fails early.
- Review my feature branch against main
- Review since commit a1b2c3d
- Review the work-in-progress changes since the v2.0 tag
- Review this PR against the merge-base with main
What the review output looks like
The agent presents two reports under the headings Standards and Spec. It does not merge or rank findings across the two, because a change can pass one axis and fail the other. Code that follows every standard but builds the wrong feature passes Standards and fails Spec, and the reverse is also possible.
The report ends with a one-line summary of the number of findings per axis and the most serious issue within each axis.
- Standards: hard violations of documented standards, with the rule cited, plus labelled smell judgement calls
- Spec: missing or partial requirements, unrequested scope creep, and implementations that look wrong, with the spec line quoted
- Each report is kept under 400 words according to the skill's brief
Tips for getting useful reviews
Give a precise fixed point. A branch name or merge-base gives the cleanest diff for a feature branch. Writing issue numbers in commit messages makes the Spec check much easier.
Keep the repo's standards written down. The Standards axis can only cite documents it can find, and a documented repo standard overrides the smell baseline.
- Use commit messages with issue references such as Closes #45
- Document standards in CODING_STANDARDS.md or CONTRIBUTING.md
- Treat smell findings as prompts for discussion, not errors
- Run your existing linters and tests separately; this skill does not run them
What people use it for
- Reviewing a feature branch against main before opening or merging a pull request.
- Checking work-in-progress changes against the project's written coding standards mid-task.
- Confirming that a branch implements what the linked issue asked for, and nothing extra.
- Getting a second look at changes from a teammate, with findings grouped by axis.
Frequently asked questions
Is the code-review skill free?
The skill is published under the MIT licence, as stated on this page. Check the repository's licence file for the full terms before you reuse or modify it.
What do I need to use the code-review skill?
You need git available in the repository you are reviewing. For the Spec check you also need access to the issue tracker or spec files; the skill references /setup-matt-pocock-skills for tracker setup. The skill runs scripts and uses the network.
How do I install a skill in Claude?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
What if my project has no spec or issue?
The Spec check is skipped and the report says no spec is available. The skill still runs the Standards review, which covers documented standards and code smells.
Does this skill run my tests or linters?
No. The skill reviews by reading the diff and does not replace existing tooling. The Standards review is also told to skip anything tooling already enforces.
How is this different from a regular linter?
A linter applies fixed rules automatically. This skill reads the diff against your written standards and the linked spec, and it flags code smells as judgement calls rather than errors.
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 this skill if you review feature branches or pull requests and want a separate check of the changes against your written standards and the linked issue. Skip it if your project has no written spec or standards and you mainly need automated linting or tests, since the skill does not run those.
Download the skill