Never Use Built-In Code Review Skills from Claude Code and Codex

My team had its own AI code reviewer. I wrote it as a skill, and the whole team used it in review. Then Claude Code got a built-in /code-review. For a while, part of our reviews quietly ran the built-in one instead of ours, and nobody noticed. We only saw that reviews got worse.

That accident taught me something I now apply to every repo. A built-in review skill can't know what matters in your code. In this article you'll see why. Then I'll show how I build a review agent skill for a repo from scratch, what sections it needs, and how it can improve itself over time. At the end you get the blueprint: the interview prompt I use and the skill structure.

A built-in /code-review gets some checks right and some wrong; a personal review agent built for the repo gets them all right

How a built-in /code-review quietly replaced our reviewer

Our reviewer knew things about our repos that no generic tool could know. The most important one: which other repos use a backend service. When someone added or removed a property in a service interface, the reviewer checked which client repos read that property. So before the merge, we knew what impact to expect.

It also knew what to ignore. We had written down the things we don't care about in review, so it stayed quiet about them.

Then the reviews changed. The agent stopped checking the client repos. False positives appeared on exactly the things we had told it to ignore. We couldn't understand why, until I looked closer. Our skill was named code-review. Claude Code now had a bundled skill with the same name.

The fix was simple. We renamed our skill to reviewer, and the old quality came back.

Lesson one: never give your skill the name of a built-in command. You won't get an error. You'll just get a different reviewer.

What built-in AI code review doesn't catch

Think about how different two repos can be:

• One is used by end users directly. Another is called only by other apps.
• One serves millions of users. Another serves 50 people inside the company.
• One calls expensive third-party APIs. Another never leaves your network.
• One is the core module of a system with ten services. Another is a small script nobody else depends on.
• One must follow GDPR or HIPAA. Another stores nothing personal.
• One has good tests. Another has none.
• One is written in TypeScript. Another in Go or Python.
• One ships ten times a day. Another has a release once a month, and a bug stays in production until the next one.
• And so on.

Do you really think one skill written by Anthropic or OpenAI can cover all of this? Of course not. The vendors know it too, so their defaults are careful. Claude Code Code Review focuses on correctness by default: bugs that would break production, not style or test coverage. Codex on GitHub flags only P0 and P1 issues. Good defaults for an unknown repo. But your repo is not unknown to you.

To be fair, you can tune both. Claude Code's managed review reads REVIEW.md and CLAUDE.md. Codex reads a ## Code Review Rules section from your AGENTS.md. I still don't use either, for three reasons:

1. They are not agent-agnostic. Each vendor reads its own file in its own way. Even inside one tool, behavior differs: the local /code-review in Claude Code doesn't read REVIEW.md at all. My team uses more than one agent, so one set of rules must work for all of them.
2. Rules in CLAUDE.md or AGENTS.md load into every prompt. Review rules are needed only when you review. During normal work they are just noise in the context.
3. Explicit beats implicit. With my own skill, I see every rule the reviewer follows.

The same goes for third-party review bots like CodeRabbit or Bugbot. I don't see the point of one more tool when a standard coding agent can do the job. And even when a service lets you customize it, you still depend on it, and it still adds its own checks that you may not need.

One more thing I tried and dropped: one shared review skill for all repos. I work on 22 repos in different languages, stacks and roles, and the number keeps growing. Some are user-facing, some are backend services, some are developer tools. A shared skill was too general for every one of them, so it failed the same way the built-in did.

Where review rules live: a skill on top of your context ecosystem

A good reviewer needs a lot of context: the architecture, the product, the security rules, the conventions. But that context is not review-specific. The agent that writes the code needs the same knowledge.

So I keep project knowledge in separate files that I call the context ecosystem. AGENTS.md is the entry point. It links to files about architecture, technical guidelines, the product, security and the repo structure. Every agent starts from AGENTS.md and opens what it needs. I described this setup in AGENTS.md vs CLAUDE.md: one setup for Claude Code, Codex and Cursor.

Context Ecosystem in the center, with Architecture, Technical Guidelines, Product, Security and Repo Structure files around it

The review skill sits on top. It runs as a separate agent with its own context, like the review subagent at the end of my cost-efficient feature workflow. It holds only the rules of review: what to check, what to ignore, how to rate it, how to report. When it needs knowledge, it points to the context ecosystem instead of copying it. The implementer and the reviewer read the same docs and don't get in each other's way.

Building a code review skill from scratch: interview first, then edit what the agent wrote

When I get a new repo and it needs a review skill, I don't write the skill by hand. I give the agent an interview prompt, and the work goes in four steps:

1. The agent reads the repo on its own. AGENTS.md and every linked doc, the stack, the database migrations, the CI setup, the history of pull requests and review comments. Then it writes a short summary: what this repo is, who uses it, what looks critical, and what it couldn't find out.
2. The agent interviews me. Rounds of up to 7 questions, only about what it couldn't learn from the code. Who uses this code? Which operations can't be undone? Which paid services does it call? What should a reviewer never comment on? What makes a finding a blocker?
3. The agent drafts the skill.
4. I review and edit it.

Five steps: the agent reads the repo, interviews you, drafts the skill; you review and edit it; Common Issues grow over time from patterns in past reviews

Step 4 is the one people skip, and it is the most important. A skill written by an agent without human review never gives a good result. The agent's draft is usually careful and detailed. It is also hard to maintain. Here is what I change most often:

• The description. The agent writes a long description of what the skill checks. A description has one job: make the agent pick the skill at the right moment. Mine says only when to use it: for any code review in this repo, before opening a PR or on an open PR.
• The context list. The draft lists the docs the reviewer should read. That list already lives in AGENTS.md. A copy in the skill is a second source of truth, and it goes stale the day someone adds a doc. I replace it with one line: follow the navigation in AGENTS.md for whatever the diff touches.
• Concrete artifacts. The draft names decision records by number, file paths and function names. I replace them with principles: "use the documented workaround for the row limit", not the name of a function.

That last change is the main rule for the whole skill. Keep mentions of specific files, paths and names to a minimum. All specifics live in the context ecosystem and AGENTS.md. The skill only points to them. When you change the docs or move files around, you don't want to remember to update the reviewer too. The reviewer should hold only the rules of review.

The structure of a good review skill

Here are the sections I put in every review skill, with a few examples for each. Your checks will be different. That is the point.

1. Scope. Which diff to read for each kind of request:

• a PR number → the PR diff, its description and the review comments already left;
• a branch → the diff against the main branch;
• nothing → the current branch plus uncommitted changes.

2. Context. Where to look before judging the code:

• the docs the diff touches, through the navigation in AGENTS.md;
• the task: the linked ticket, or the task stated in the PR description;
• open issues, only for reminders (see section 6).

3. Checks. This is the heart of the skill. Group the checks by area, and keep only the areas that matter in this repo. For example:

• Task. The PR links a ticket or states its task; without one there is nothing to review against. The diff does what the task asks, and unrelated changes are called out. The description says how it was tested.
• Data. Schema changes are safe for the data already in production. A destructive change has a way back: a backup, a rollback or a recovery plan.
• Backward compatibility and public interfaces. A change to a public interface (an API, events, an SDK, a shared schema) doesn't break its consumers. The reviewer checks the consumers it can reach. A breaking change is explicit, versioned and comes with a notice, so clients know what they must support and by when.
• Irreversible actions. Anything that can't be undone, like deleting data or sending something to an external system, is guarded. A retry can't run it twice.
• Personal data and secrets. No real personal data in code, test data or the PR text. No keys in the client bundle.
• Architecture. Business logic stays in its layer. New code is consistent with the existing code and follows the repo's file structure. External integrations are taken into account: their limits, failures and contracts. Errors are logged or rethrown, never swallowed. A new pattern gets a decision record.
• Tests. Critical areas are covered by tests. Every test that is written is useful: it can actually fail and checks behavior, not the implementation.
• Docs. All docs match the actual code: no contradictions, nothing outdated, every link works.

4. Do not report. What the reviewer must stay quiet about:

• anything lint and type checks already catch;
• generated and vendored files;
• "could be a problem if…" without a concrete scenario in this codebase.

5. Severity. What Blocker, Major and Minor mean in this repo:

• Blocker: data loss, a broken contract, personal data in git;
• Major: a critical area without tests, a swallowed error, docs that contradict the code;
• Minor: naming, small convention slips. If unsure between two levels, pick the lower one.

6. Reminders. When the diff touches code with a known open issue, add a one-line reminder. It is not a finding and doesn't change the scores.

7. Report format. One fixed shape for every review, so you can judge the result at a glance. That matters when you have many pull requests to go through. Mine starts with a verdict, a confidence score and a table of scores per area. I cover the format in the next article of this series.

A review report: verdict, confidence score with merge danger, a table of scores per criterion with a short reason, issue counts by severity, then fixed sections from What this PR does to Reminders

8. Delivery. Where the report goes:

• local changes → in the chat;
• a PR → shown to me first, then posted as one review;
• the reviewer never commits fixes without a direct command.

9. Common Issues. The section that makes the skill improve itself. More on it below.

Self-improving: keep a Common Issues section

Always keep a Common Issues section in your review skill. It can start empty.

This section collects the mistakes that keep coming back in this repo: the things human reviewers flag again and again, and the reviewer missed. When the same kind of issue shows up in two or more PRs, it becomes a candidate for this section. After a human approves, the reviewer starts checking for it on every PR.

You can fill it by hand. But the real win is to let an agent do it on a schedule: read recent reviews, find the patterns the reviewer missed, and propose new Common Issues for you to approve. That is how a review skill gets smarter every week without your effort. I'll show the full setup in a later article of this series.

Build your own reviewer this week

The result in my team: on my own pull requests, the reviewer finds at least one thing I didn't think about, usually two to four.

To make your first one, take the Agentic Code Review Blueprint below. It has the interview prompt I use (with the lessons from this build) and the full skill structure with examples for each section. Run the prompt in your repo, answer the questions, and edit the draft.

Get the Agentic Code Review Blueprint

Next in this series: the review report format that lets you see the state of any PR in seconds.

FAQ

Can I just use REVIEW.md instead of a skill?

You can, if your team uses only the managed Claude Code Code Review on GitHub. The local /code-review command doesn't read it, and Codex reads its own rules from AGENTS.md instead. A skill in a shared folder works for every agent.

Does Codex read review rules from AGENTS.md?

Yes. Codex code review on GitHub reads a ## Code Review Rules section from the nearest AGENTS.md (docs). But those rules then load into every Codex task in that repo, not only reviews. OpenAI's own best practices suggest keeping review guidance in a separate file and linking to it from AGENTS.md. That is close to what a review skill does.

Why not CodeRabbit or Bugbot?

They work, but they add one more tool and one more dependency. A standard coding agent with your own skill does the same job, and you control every rule it follows.

How long should a review skill be?

Reasonable. A very long skill usually means you are copying something from your context ecosystem into it. Move it back and link to it instead. My review skills are usually 100 to 300 lines.

What should I name my review skill?

Anything that isn't a built-in command. Not code-review, not review. I use reviewer.