Agent Skill for Code Review

An agent skill for code review is a reusable review procedure that tells an agent what kind of pull request it is reviewing, which project rules matter, what evidence to gather, and how to report findings without turning the review into a generic essay.

The useful boundary is simple: the agent skill does not replace human code ownership. It makes repeatable review work more consistent. GitHub's pull request review model still has human-facing outcomes: comment, approve, or request changes before merge (GitHub pull request reviews). A code review skill should help an agent produce evidence that a human reviewer, maintainer, or author can inspect.

This is exactly the kind of workflow that belongs in a skill rather than a one-off prompt. OpenAI's Codex Agent Skills package reusable instructions with optional scripts, references, and assets. Anthropic's Agent Skills overview frames skills as packaged domain expertise and organizational knowledge. Code review needs both: the procedure for reading a pull request and the team's local rules for what counts as a blocker.

If you are still deciding where skills sit in an agent stack, start with What Is an Agent Skill?. For code review, the short version is this: use a skill when the problem is inconsistent reviewer judgment, not missing repository access.

The minimum viable code review skill has five parts: scope, trusted references, review sequence, severity rubric, and output format. Without those, the agent may still review code, but the review will be hard to repeat and hard to audit.

A code review skill should narrow the review to a named job, force diff-first inspection, require project-specific evidence, and return only actionable findings. The skill should also say what the agent did not verify.

That matters because "review this PR" is too broad. A broad instruction invites the agent to comment on style, architecture, naming, tests, security, docs, and performance all at once. A narrower skill can encode the review a team actually wants.

Review skill	What it should inspect first	Evidence that makes a finding credible
Security review	Auth boundaries, secrets, injection paths, authorization checks	Exploit path, affected route, missing guard, failing or absent test
Analytics review	Event names, required properties, funnels, dashboards	Taxonomy reference, changed payload, affected query or chart
Migration review	Deprecated APIs, compatibility layer, rollout plan	Old usage, accepted replacement, version constraint, focused test
Frontend review	Empty states, loading states, keyboard flow, responsive layout	Route, viewport, screenshot, accessibility role, reproduction steps
Release readiness review	Config, feature flags, migrations, monitoring, rollback	Deployment surface, flag state, migration command, observability gap

The review type should appear in the skill name, description, and first section. A skill named code-review can work, but security-pr-review, analytics-review, or react-accessibility-review will usually produce better results because the agent has less room to improvise.

Use a sequence the agent can actually follow:

1. Identify the review type and the user's requested scope.
2. Inspect the pull request diff or changed files before broad repository search.
3. Read nearby tests, affected call sites, and project references.
4. Compare the change against the skill's rubric.
5. Run focused checks when the environment allows it.
6. Report blocking findings first, with file path, line reference when available, impact, evidence, and suggested fix.
7. Separate required changes from optional suggestions.
8. State residual risk: tests not run, paths not inspected, missing credentials, unavailable services.

Google's code review guidance is useful here because it gives the skill a review philosophy, not just a checklist. Its standard says reviewers should favor approval once a change improves the codebase overall, even if the change is not perfect (Google Engineering Practices). That principle is important for agent review skills. The agent should not block a pull request over a preference unless the skill explicitly defines that preference as a team rule.

GitHub's own staff engineering guidance makes the same operational point from another angle: good reviews make clear which comments are blockers and which are personal preference, and examples from the same repository make suggestions stronger (GitHub staff engineer code review philosophy). Encode that distinction directly in the skill.

Do not leave severity labels to taste. Put the rubric in the skill.

Severity	Use when	Example finding
Critical	The change can cause data loss, auth bypass, secret exposure, failed deploy, or major outage	New route omits the organization membership check before returning billing data
High	The change creates a user-visible regression, broken workflow, incorrect data, or serious maintainability risk	Checkout success still redirects, but the purchase event drops plan_id, breaking revenue attribution
Medium	The defect has limited blast radius or a workaround, but should be fixed before or soon after merge	Error state exists on desktop but not on mobile settings view
Low	The issue is clarity, naming, small cleanup, or non-blocking follow-up	New helper duplicates an existing pattern in the same module

A useful skill also tells the agent when not to comment. For example: "Do not report style nits unless they affect readability, violate an existing lint rule, or the user explicitly asked for style feedback." That one line prevents a lot of noisy reviews.

AI code review tools make this pattern more important, not less important. GitHub Copilot code review can review pull requests and local changes, can be configured for automatic review, and can use repository custom instructions. GitHub's documentation also says Copilot code review can use repository agent skills under .github/skills and MCP servers when the context is relevant, with review-focused skill names and descriptions making use more likely (GitHub Copilot code review).

That is a strong signal for skill authors: repository-local review guidance is becoming part of the code review surface. This pattern also shows up outside GitHub. CodeRabbit supports path-based review instructions for controllers, tests, docs, and other glob-matched areas, and its docs recommend targeted instructions as a supplement when a reviewer consistently misses something in a specific part of the codebase (CodeRabbit path instructions). GitLab Duo can review merge requests for potential errors and alignment to standards, with different context depth depending on the review mode (GitLab Duo in merge requests). Cursor Bugbot describes a similar product goal: automatic PR review tuned toward real bugs and custom rules.

A review skill should therefore be written like production developer tooling, not like a private prompt. The target is not "make the AI reviewer smarter" in the abstract. The target is "make this review repeat the team's standard with fewer false positives and fewer missed blockers."

There are tradeoffs:

Approach	Works well for	Risk
Generic AI reviewer	First-pass comments on obvious bugs or simple patterns	Superficial suggestions, missed project-specific rules, repeated comments
Repository custom instructions	Broad house style and persistent repo context	Too general for specialized reviews
Review-focused agent skill	Repeatable review type with clear evidence and boundaries	Needs maintenance as the codebase and review policy change
Deterministic checks	Lint, type errors, schema validation, test failures	Cannot judge design intent or ambiguous tradeoffs

Community reports around AI reviewers tend to orbit the same issue: a more explicit review procedure often produces higher-signal findings than a default product pass, especially when the prompt names the diff source, limits comments, blocks duplicate feedback, and requires high-severity evidence. Treat that as a design lesson, not proof that one vendor always wins. A code review skill should make the review procedure inspectable and adjustable.

This is why Agent Skill vs Tool: What Is the Difference? is not just architecture theory. The GitHub tool or MCP server gives the agent access to pull requests, files, issues, CI, or browser state. The skill decides what a serious review means.

A code review skill should not ask the model to mentally do work that code can do exactly. Put judgment in the skill. Put deterministic checks in scripts, linters, tests, or tools.

Skill instructions should say:

• Read the diff before searching unrelated files.
• Treat missing auth checks on billing routes as blocking.
• Compare analytics events against docs/analytics/events.md.
• Mark style-only comments as Low and do not block on them.
• Do not post GitHub review comments unless the user explicitly asks.

Scripts and tools should handle:

• Parse changed files.
• Run npm test -- checkout.
• Validate event payloads against a schema.
• Query CI status.
• Capture a browser screenshot for a changed route.
• Fetch linked issue or incident context through MCP.

For a deeper split between procedure and automation, see Agent Skill vs Code: What Should Live in Instructions?. Code review skills are strongest when they use code for exact checks and reserve prose for reviewer judgment.

Suppose a product team ships a new onboarding flow and wants an agent to review the pull request for analytics regressions. A generic review prompt might say: check event names, verify properties, and make sure tracking works. That sounds plausible, but it is not enough.

A real analytics review skill should encode the team's event contract:

Review scope: analytics instrumentation only.

Trusted references:
- `docs/analytics/events.md`
- `app/src/analytics/event-registry.ts`
- nearest tests for the changed route

Process:
1. Inspect the diff.
2. List every added, removed, or changed tracking call.
3. Compare event names and properties against the registry.
4. Treat missing required properties as High.
5. Treat unregistered events as High unless the PR updates the registry.
6. Run the focused analytics tests if dependencies are available.
7. Return only actionable findings.

Now the agent has a real job. If the new onboarding completion event omits skill_id, the review can point to the changed tracking call, cite the registry, explain which dashboard or funnel depends on that property, and suggest either restoring the property or intentionally updating the contract.

That is the difference between "review this code" and a code review skill. The first depends on taste in the moment. The second carries institutional memory.

Migration reviews are another strong fit because the accepted answer is often buried in release notes, internal docs, or old pull requests.

Imagine a team moving from a legacy billing API to a new subscriptions API. A migration review skill should tell the agent to find changed imports, compare each call against the migration guide, check compatibility flags, and look for mixed old/new data shapes. It should not ask for a general architecture review unless the user asks for one.

A useful finding might look like this:

High - `app/src/billing/checkout.ts:118`

The PR replaces `createLegacySubscription` with `createSubscription`, but still passes `couponCode`.
The migration guide says the new API expects `discount.code`, and the adjacent test only covers the no-discount path.

Fix: map `couponCode` into `discount.code` and add a discount-path test before merge.

Notice the shape: location, impact, evidence, fix. That format is easy for a maintainer to validate.

Require a compact review report. Do not let the agent bury findings in a narrative.

## Findings

1. High - `app/src/checkout.ts:84`
   The checkout success event no longer includes `plan_id`, but the revenue funnel groups by that field.
   Evidence: changed payload removes `plan_id`; `docs/analytics/events.md` still marks it required.
   Fix: restore `plan_id` or update the taxonomy and dashboard query in the same change.

## Suggestions

- Low - `app/src/checkout.ts:41`
  The new helper duplicates `buildCheckoutContext`; consider using the existing helper in a follow-up.

## Residual risk

Focused analytics tests were not run because dependencies are unavailable in this environment.

This is much easier to act on than a long unordered critique. It also creates review data that a Skillfully author can improve over time: which findings were accepted, which were noisy, and which rule needs to be clarified.

Before publishing or sharing the skill, check the authoring surface:

• The skill name identifies the review type.
• The description makes the trigger condition obvious.
• The first section defines the review scope.
• The skill requires diff-first inspection.
• Trusted references are named with file paths.
• Severity labels are defined.
• Findings require evidence and suggested remediation.
• The agent is told when not to comment.
• Tool permissions and side effects are explicit.
• The output format separates blockers, suggestions, and residual risk.
• The skill says whether the agent may edit code or only review it.

For Skillfully authors, this is also a feedback loop. How to Test an Agent Skill Before You Publish It covers the validation side: run the skill against realistic pull requests, inspect whether the findings were accepted, and revise the instructions where the agent missed the team's actual standard.

The first mistake is making one giant "senior engineer review" skill. Split repeated jobs into smaller skills: security review, accessibility review, migration review, analytics review, release readiness review.

The second mistake is failing to name the trusted sources. If the skill says "check analytics," the agent may infer a rule. If the skill says "compare every event against docs/analytics/events.md and event-registry.ts," the review becomes auditable.

The third mistake is allowing side effects by default. Reading a pull request, running tests, and reporting findings are review actions. Posting GitHub comments, requesting changes, pushing commits, or applying fixes are side-effect actions. The skill should require explicit user approval before those happen.

The fourth mistake is treating all feedback as blocking. Some changes must be fixed before merge. Some suggestions are better as follow-up issues. Some comments are only useful if the author asked for that kind of feedback.

An agent skill for code review should make a review more specific, evidenced, and repeatable. It should not make the agent louder.

Use tools to reach the pull request, run tests, inspect CI, or fetch issue context. Use code for deterministic checks. Use the skill for the review procedure: what to inspect, what standard to apply, when to block, when to suggest, and what evidence to return.