Agent Skills for Code Review: A Reliable Workflow

What a review skill should standardize

A code-review skill should make the review procedure repeatable without pretending that a checklist can replace engineering judgment. Its job is to establish the evidence order, defect threshold, severity language, verification steps, and output contract an agent follows.

The Agent Skills specification provides the portable SKILL.md structure. The OpenAI skills guide and Claude Code skills guide explain how current clients discover and activate skills. The workflow itself should remain useful even when the host, repository, or programming language changes.

A strong description says when the skill applies: reviewing a pull request, branch diff, patch, or staged change for correctness and regression risk. It should not activate for a general explanation of code unless that is an intentional secondary use case.

Start by reconstructing intent

Reviewing lines without understanding the requested outcome produces noisy feedback. The skill should first collect:

1. The change request, linked issue, or stated acceptance criteria.
2. The base and head revisions that define the complete change.
3. Repository guidance, ownership rules, and relevant architecture notes.
4. Tests, migrations, generated files, dependency changes, and configuration touched by the change.
5. Any explicitly excluded scope.

GitHub's official pull-request review guidance recommends understanding the purpose of the pull request and examining the changed files before submitting a review. A skill can encode that order, while stopping and asking for context when the goal or comparison range is genuinely ambiguous.

Inspect the complete change, not only the patch

A diff shows what changed, but a defect often depends on code outside the changed lines. After reading the diff, follow symbols into callers, data models, tests, configuration, and public interfaces. Check both additions and deletions. Review lockfiles and migrations rather than treating them as incidental noise.

The workflow should distinguish:

• Observed behavior: what the code and tests currently demonstrate.
• Required behavior: what the issue, contract, or existing interface requires.
• Inference: a plausible concern that still needs validation.

Only the first two can support a confident defect finding. If a concern depends on missing runtime context, label it as a question or verification gap rather than a confirmed bug.

Prioritize concrete defects

Require every finding to contain four parts:

1. A specific file and the smallest useful line range.
2. The input or execution path that triggers the problem.
3. The user, data, security, or operational impact.
4. A concise explanation of why the new change causes or fails to prevent it.

Useful severity levels are tied to impact, not tone. A blocking finding might expose data, corrupt state, break a common path, or make the change unsafe to ship. A lower-severity finding might affect an edge case or make recovery unreliable. Style preferences should not be presented as correctness defects unless the repository's enforced rules make them build-breaking.

The skill should suppress duplicates, combine findings with the same root cause, and rank by severity. If no qualifying defect remains, say so clearly and list meaningful residual risks or untested areas.

Review tests as evidence

Tests are part of the change, not proof by declaration. The review should ask:

• Does the test fail against the old behavior and pass against the intended fix?
• Does it exercise the externally observable contract rather than an implementation detail?
• Are important error, boundary, authorization, and rollback paths represented?
• Can the assertion pass for the wrong reason?
• Did the change invalidate existing tests that were merely updated to match it?

Run the narrowest relevant checks first, then expand according to risk. Record what actually ran and what could not run. Never claim a suite passed from reading CI configuration or test names.

Check risk boundaries explicitly

A general review sequence should include:

1. Correctness and state transitions.
2. Authentication, authorization, and tenant boundaries.
3. Input validation and unsafe output handling.
4. Data migrations, compatibility, and rollback.
5. Concurrency, retries, idempotency, and partial failure.
6. Resource use, caching, and performance regressions.
7. Observability and diagnosability.
8. Dependency and supply-chain changes.

Not every category applies to every diff. The skill should select relevant checks from repository evidence instead of generating one comment per checklist heading.

Keep review and mutation separate

A review skill should default to read-only analysis. Commenting, approving, requesting changes, editing code, pushing commits, or merging are separate actions with distinct authority.

If the host provides repository tools, make the workflow stop before any external mutation unless the user has explicitly requested it. A skill's prose cannot enforce branch protection or repository permissions. Those controls remain with the host, Git provider, and human review policy.

Define a useful output contract

A compact review result usually works best:

• Findings first, ordered by severity.
• Each finding anchored to the changed code and supported by a trigger path.
• Open questions only when they materially affect the verdict.
• A short verification summary naming checks actually run.
• A clean “no findings” outcome when evidence does not support a defect.

Avoid long summaries that bury actionable issues. Avoid praise, speculative rewrites, and generic best-practice lectures. The author should be able to reproduce each finding and understand its impact without rereading the whole change.

Validate the skill before relying on it

Test the skill against reviewed examples:

1. A change with a clear high-impact regression.
2. A change with a subtle edge-case defect.
3. A correct change that should produce no findings.
4. A large diff where the important bug sits in a caller outside the patch.
5. A change with insufficient context where the correct result is a question.

Measure false positives, missed seeded defects, duplicate findings, evidence quality, and whether severity matches impact. Re-run the evaluation when the skill, model, host tools, or repository conventions change. A maintained review skill is a versioned engineering policy, not a one-time prompt.