Agent Skill: Peer Review

A peer-review skill is useful when it treats the repository as the source of truth and requires evidence for every finding.

Adarsh Trivedi · August 20, 2025 · 3 min read

Takeaway: Good agent review is not a list of opinions. It is a small number of claims backed by repo rules, sibling code, or a check that actually ran.

What it does

This skill reviews someone else's pull request. It first looks for the repository's own guidance: working agreements, contribution docs, local agent files, design notes, or sibling patterns.

Then it reviews the diff against that context. The important constraint is that every finding needs a receipt: a rule, a neighboring implementation, or a reproducible check.

Why it helps

It reduces two common review problems: generic advice and confident-but-wrong comments. The skill is intentionally read-only until comments are approved, so it stays a reviewer instead of becoming a surprise implementer.

Sanitized skill notes

This is the public version of the saved skill markdown. I removed machine paths, repository names, and private review references.

name: peer-review
purpose: Review another person's pull request using the repository's own rules.

not for:
  - silently editing the author's code
  - reviewing from memory
  - posting comments without approval

workflow:
  1. Find the repository guidance.
     Look for working agreements, contribution docs, local agent files,
     architecture docs, and nearby examples.

  2. Read what the PR claims.
     Review against the stated intent, not a different design preference.

  3. Review in passes.
     - conventions from the repo docs
     - reuse of existing helpers, components, and patterns
     - sibling consistency in nearby code
     - correctness, empty states, boundaries, and failure paths

  4. Verify before writing a finding.
     A finding needs a receipt: a rule, sibling code, or a check that ran.

  5. Ask before posting.
     Draft review comments first; only post after explicit approval.