Writing a /review your team actually runs
A /review skill that flags the few things your team keeps catching — ranked worst-first, scoped to the diff, and short enough that people actually run it.
The /review you already have, and don't run
I assume you have the review command already set up but nobody uses it
Most of agent frameworks come with a review command out-of-the-box, for example:
Claude Code:
/reviewCodex:
codex reviewCopilot:
/reviewand/rubber-duckCursor: a pre-packaged review skill
But let's say you create a PR — do some renaming, ask about sth, suggest to extract a helper function — and there's this actually crucial thing in point no. 7, below the fold: If you were to use the builtin version of the review command for it you'd be like: "Hm, that's nice", read it once or twice and stop using it at some point.
It's not about the model, it's just that if a tool doesn't know what you don't like it can only tell you everything it considers to be good. A perfect review must do two things that the builtin version of the review command can't:
Know your team's top 5 pet peeves
Be short enough so people actually read it
If you were to create such a skill and share it with your team — it'd be like everyone in the team runs it; it's like you document it once and then every team member uses the same recipe, just in a different framework with a slightly different file location and trigger.
What makes it worth running
It's useful if:
You limit it to the diff (and surrounding lines), not the entire file/module — the biggest noise that the builtin version creates is commenting on what hasn't changed
You order by severity (from 3 categories: blocking, should-fix, and optional) and put the most serious things first; if you're certain there's nothing blocking you can let it know explicitly — if a tool can't say "nothing", it's gonna be like: "Okay, I'll find sth" and will come up with a nit, which in return makes it untrustworthy
Each finding must say where (line number) and what (what's the problem and how the change breaks it), "renaming this to foo" doesn't work here, but "this will throw on empty array because we access element 0 on line no. 40" does — if you don't point to a bug it's just an opinion and nobody wants a tool that tells them opinions
You exclude everything that your formatter, linter or type checker are already telling you about — nobody reads the CI output twice
You tell it what your team actually cares about — this is the most important part. It's not about ideal code but about things your senior dev points at every time after each PR you submit; not a best-practices language, but the actual "hmmm"-s that your team members say during reviews
The team part is the whole point
The thing that differentiates a perfect review from a builtin one is that it's not generic — it's yours. It's not a list of industry's best practices, it's a list of things that your senior dev would point at if you were to ask her to have a look at the change. That's what decides whether you use sth or mute it. Don't try to come up with this on your own — collect the most recent 20 comments from the PRs you created and analyse the 5 things your teammates wrote more than once, these are the things that they actually say after looking at your code, so these are the best practices for your team, not some generic ones from an article.
Aim for 3 points with severity set, these are the ones that get addressed, if you hit 30 — nobody reads it and you have the second thing to ignore
In Claude Code
The skills are stored in the files like .claude/skills/<name>/SKILL.md and you can reference it using the folder name (like /review). Create a file at .claude/skills/review/SKILL.md and commit it to the repository so that it's available for the other users as well. This is a per-user configuration so if you create it at ~/.claude/skills/ it will be for you only, for example. It's effective immediately and doesn't require the restart.
You can set few things in the frontmatter of the file:
namedescriptiondisable-model-invocation
---
name: review
description: Review the current change against our standards, worst first
disable-model-invocation: true
---The most important one is the latter as if you set disable-model-invocation: true it means that Claude won't ever invoke this skill automatically and it will be user-triggered only. That's perfect for deliberate checkpoints like /review as then it doesn't pollute the context of the chat (and hence it costs nothing) until the user runs it.
You can also use the $ARGUMENTS token in the body to replace the text written after the command, like so: /review the billing retry narrows scope
But be aware that both /review (as GitHub PR review) and /security-review are already defined in Claude Code, so the name is not great if you want to create it. You can go with team-review instead so it's unambiguous and can be run like /team-review.
In Codex CLI
The first place where Codex looks for a skill is in your ~/.codex/skills directory, and the second one is in .codex/skills or .agents/skills directories at the root of your repository. The file name is just SKILL.md and it sits in a directory named after the skill (~/.codex/skills/<name>/SKILL.md). Its frontmatter (that is name and description fields) is the same as for a skill, and the body is the same as everywhere else.
You need to call it using $, e.g. $review, but not with a slash (like /review), because the latter won't work — the /skills menu is only to explore available skills. If you want the skill to be triggered manually, consider setting its description to be more narrow, because Codex automatically loads a skill when it finds that the user's request matches the description.
If you ever wondered, there are actually two ways of doing code review in Codex already — a built-in non-interactive codex review command (handy from a script) and a system skill called review-agent that ships already installed, both of them generic and superseded by this recipe. The old custom-prompt solution (~/.codex/prompts/review.md) bound to /review still works, but OpenAI marked it as deprecated in favour of skills, so it's best to go with the skills from the start.
In GitHub Copilot CLI
Copilot recognises skills based on the existence of SKILL.md files (under .github/skills/, or .agents/skills/, or .claude/skills/) — so if you create a skill for another tool, it will automatically work with Copilot as well — or you can add one with copilot skill add <dir>. You can list recognised skills with copilot skill list and see where they are defined from, to check if a file sits in the right place.
The most important difference compared to other tools is that this isn't a slash command. Instead, the agent decides on its own to use it based on the value of the description field, whenever you ask it to "review the changes" in natural language — so make sure to set up the description in such a way, that it will be used only for this purpose. E.g:
description: "Use when the user asks to review a diff or pending change before it merges"
In the neighbourhood there's also Copilot's own /review (general-purpose reviewer), and /rubber-duck (a second opinion).
In Cursor
Cursor commands are regular Markdown files that can live in two places - in your repo in .cursor/commands/ folder (shared with the team) and in ~/.cursor/commands/ (which is for your personal use). The name of the file becomes the command itself so for example if you create file called .cursor/commands/review.md it will result in /review command. In these files you can access the arguments typed after the command using $ARGUMENTS variable. To create a new command just drop the recipe in there (the prompt), optionally with frontmatter and that's it.
Alternatively, you can define your own Cursor skill in .cursor/skills/<name>/SKILL.md file but setting disable-model-invocation: true so it's only runnable manually if that's what you prefer over a command. But beware there are 3 skills shipped with the base version of the app - review, review-bugbot and review-security (the general ones) so /review might point to one of these. Name your command team-review.md if you want it to be unambiguously yours.
In Gemini CLI
You can create custom commands and save them as TOML files in two locations:
~/.gemini/commands/— your own.gemini/commands/in the project — shared with the team
The name of the file becomes the name of the command so review.toml is /review. The prompt key contains an instruction, {{args}} is a placeholder for what you type after the command. For example:
description = "Review the current change against our standards, worst first"
prompt = """
Review the current change — the diff, not the whole files.
Report findings in three tiers, worst first: blocking, should-fix, optional. Say
so in one line when a tier is empty. For every finding give the location, what's
wrong, and the concrete failure it causes. Skip what the linter already catches.
The change to review: {{args}}
"""The description is optional but appears under /help so you might consider adding it. You can create subfolders in commands/ to have namespaced commands like /pr:review when it's commands/pr/review.toml.
The future of Gemini CLI might be a bit uncertain as Google switched consumer users to Antigravity CLI this mid-2026; OSS and enterprise users continue with the Gemini CLI. The Antigravity CLI also expands slash commands and skills so make sure you check where exactly it looks for them before relying on this particular path.
In Kimi Code CLI
Kimi Code allows to define and use your own skills using its CLI. There are multiple places where you can put these definitions:
in your local home directory:
~/.kimi-code/skills/in the repository, either in
.kimi-code/skills/or.agents/skills/at the root of itas a separate folder with
review/SKILL.mdfile in it, or as a singlereview.mdfile
The frontmatter here has a few additional fields compared to other tools:
---
name: review
description: Review the current change against our standards, worst first
disableModelInvocation: true
arguments:
- target
---To invoke it you need to run /skill:review, but /review won't work (the prefix is a Kimi thing). If you want to disable the model from running this skill on its own, you can set disableModelInvocation: true. The arguments are named ones as well, so you need to define your target under arguments, and refer to it in the body of the skill using $target variable. The text following the /skill:review is being set in the $target variable too (so you could write there "the auth refactor" for example)
Running it, and tuning it until it sounds like you
So it's all about incorporating your team's standards in it, but you run it before pushing (or ask a colleague to have a look at the branch), just like you'd use /goals. That's the value of such commands — that you decide when you want to use them. You can set up a pre-push hook or a headless PR check (we'll get to it in later lessons) but it's best to start with the manual version first.
Then it's all about perfecting it, line by line:
If it complains about sth you don't care about — remove this standard
If you do the review and think "hm, actually it missed sth here" — add a new standard
Then after a week it becomes your team's review rather than some best-practices list which is the only kind that people use
Where teams get this wrong
There are two opposite ways this goes wrong:
it can be too talkative: then it's comprehensive and contains valuable info, but it's just too noisy to use, so people stop using it after a week
or it can be a yes-man: then it won't say anything that might be disagreeable, so it's only performative, and people don't trust it and ignore it as well
The perfect review is either like: "Here's one real problem I found", or "I don't see anything serious". In both cases you trust it. It's not a replacement for a human reviewer nor for CI — it's about addressing a particular category of problems, in the 10 seconds before pushing. If you were to give it the entire responsibility of a senior dev — it would do this job badly; if you were to give it your team's top 5 pet peeves — it will get the job done
.claude/skills/review/SKILL.md---
name: review
description: Review the current change against our team's standards, worst problems first. Use when asked to review a diff, branch, or pending change before it merges.
disable-model-invocation: true
---
Review the current change — the diff, not the whole files. Look at what changed (staged and unstaged) and the lines immediately around it. Ignore code this change didn't touch.
Report findings in three tiers, worst first. If a tier is empty, say so in one line and move on — don't pad it.
**Blocking** — a bug, a security hole, data loss, or a broken build. Must not merge.
**Should fix** — a real problem that isn't a blocker: a missed edge case, an unhandled error, a test that doesn't test what it claims.
**Optional** — a genuine improvement you'd raise in review, clearly marked optional.
For every finding, give three things: where it is (file and line), what's wrong, and the concrete failure it causes. "Consider renaming this" is not a finding. "Throws on an empty list because line 40 indexes [0]" is. If you can't name the failure, drop it.
Skip anything the formatter, linter or type-checker already catches. Don't comment on style the tooling owns.
## What this team cares about
Replace this list with the notes your reviewers actually leave. The more specific, the more this gets run — seed it from your last twenty PR comments, not from a best-practices article.
- Errors are wrapped with context, never silently swallowed.
- No secrets, tokens or credentials in committed code or logs.
- New behaviour has a test that would fail without the change.
- Public functions say, in one line, why they exist.
End with a single line: the one thing to fix before this merges, or "Nothing blocking" if there isn't one.
The change to review: $ARGUMENTS