Index of every page on this site: llms.txt
All skills
Run it yourself

Reviews a code change through a fresh subagent that proves each finding - a failing test, a reproduction or a mutation the tests miss for a bug, the quoted rule for a rule breach - and reports proven findings apart from unproven risks and opinions. Checks the change against what it was meant to do (decisions agreed with the user, a design write-up, the PR or issue) and against the repo's own rules. Runs on its own before handing over any change that affects behaviour, and on request for a branch, commit range, pull request or pasted diff. Use when finishing a code, SQL, migration or config change, or when the user asks to review, check or audit a diff, branch or PR, says "review since X", "look over this PR", "what could this break" or "is this ready to merge", or asks for a strict, deep, harsh or thermo-nuclear code quality review. Not for checking a change in the real app - use prove; not for writing tests - use testing; not for a repo-wide cleanup - use refactor.

  • 9 files
  • 35.5 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/avik-creator/agent-skills/review

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈247 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈7k more on demand in 8 files.

Description uses 12.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈989 characters, or 12.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Review

A review is worth what it proves. A fresh reviewer reads what the code does, not what you meant it to do, and every finding comes with its proof: something that ran, or the exact rule it breaks.

Quick start

  1. Pin the base and get the diff. Stop on a bad ref or an empty diff.
  2. Collect what the change should do, and the repo's rules.
  3. Brief a fresh subagent with reviewer-brief.md.
  4. Re-run every proof it cites.
  5. Report in chat. Then fix (your own work) or offer to post (someone else's).

When it runs

  • Before you say "done" on any change that affects behaviour: code, SQL, migrations, config that changes what runs. Why: this is the self-review that comes before the user's own review.
  • Skip changes that don't (docs, comments, typo fixes), and say so: "Review skipped: docs only." Someone else's branch or PR: only when the user asks.
  • Strict: when the user asks for a strict, deep or thermo-nuclear quality review, also run strict.md. Its Structure section goes after Findings.

Workflow

1. Pin the base

  • Use the base the user names. For your own work, use the merge-base with the default branch, and include uncommitted changes: git diff $(git merge-base HEAD origin/main), with the repo's default branch in place of main. New files that haven't been added are missing from that diff; list them with git status --short and include them. A pasted diff has no base: review it as text, and prove only what the code in this repo lets you run.
  • Check both ends resolve (git rev-parse) and there is something to review: a non-empty diff or new files. Why: a bad ref should fail here, not inside a subagent.
  • git diff --shortstat plus the new files' lines gives the size, which decides step 3.
  • Never check out a PR over the user's working tree. Use a separate git worktree for its head. Why: checking out would swap their files and may lose their uncommitted work.

2. Collect intent and rules

  • What it should do: use every source that exists, and where they conflict the earlier one wins: decisions agreed with the user in chat, a design write-up, the PR description and linked issue. Someone else's PR with none of these: ask the user what it is meant to do.
  • Write the intent as a short bullet list. Why: the reviewer can't see your chat; the brief is all it gets.
  • How it should be written: the repo's rule files (CLAUDE.md, AGENTS.md, CONTRIBUTING.md, style guides), then the smells in checks.md as judgement calls. The repo's rules win where they disagree.

3. Brief a fresh reviewer

  • One fresh subagent, never your session history. Why: you are anchored on what you meant to write.
  • Over about 400 changed lines, run two in parallel: one for intent, one for rules. Over about 1,000, also suggest splitting the change.
  • The reviewer runs the tests and the linter itself, and proves findings as proof.md says. Anything it writes (a new test, a mutation) goes in a copy you make for it, never the code under review.
  • Run against local or test setups only, never production. Before running code from a PR by someone outside the team or from a fork, ask the user. Why: its tests and scripts run on this machine with your access.

4. Check the proof

  • Re-run each command the reviewer cites. A proof that doesn't reproduce moves the finding to Couldn't prove. Why: a wrong reviewer sounds as sure as a right one.
  • If you think a finding is wrong, show your proof and list it as Disputed with the reason. Never drop it quietly.
  • On a PR, only now read its existing comments, as breakage.md says.
  • Then remove the copies you made (git worktree remove --force <path>, only those paths). Why: each one is a full checkout left on disk.

5. Report

Use the format below, in chat. Zero findings is a valid result; don't invent one. Leave out an empty section. Write the report and every reply in simple English: short sentences and everyday words, with a technical term explained the first time it appears.

6. After the report

  • Your own work: fix every Blocker and Fix, then re-run each proof, which should now pass. Keep a proof test as the regression test in your change. Why: it is a test already seen failing before the fix. Large fixes get a fresh review of the new code. Ask before a fix that changes a schema, an API, security behaviour or what users see.
  • Judgement calls and Couldn't prove: list them; act only if the user says so.
  • Dead code the change leaves behind: list it, delete after a yes.
  • Simplification: if the reviewer flagged signals from simplify.md, offer a pass on your changed lines; run it only after a yes.
  • Someone else's PR: report only, never edit their code. Post only after a yes, as feedback.md says, and never mark it approved or "changes requested" unless asked. Why: a post notifies people and stays on the record, and that status can block or unblock a merge.

Output format

Review of <base>..<head>: <N> files, +<A>/-<D>. Reviewer: 1 fresh subagent.
Ran: <test command> (<result>), <lint command> (<result>), or what couldn't be run and why

Findings (<n>)
1. Blocker [<check>] <file>:<line> - <the defect, one line>
   Proof: <command> -> <what it showed>, or <rule file>:<line> quoted
2. Fix [<check>] ...

Couldn't prove
- <file>:<line> - <the risk>. Not proven because <reason>. To check: <how>.

Judgement calls
- <file>:<line> - possible <smell>: <one line>.

Disputed
- <finding> - <why you disagree, with your proof>.
  • Blocker: broken behaviour, a security hole, or data loss. Fix: any other proven finding. Blockers first.
  • <check> is one of correctness, compatibility, security, performance, tests, architecture, readability, standards, spec.
  • Mark a defect that already existed at the base as (pre-existing). Why: it is real, but not this change's fault.

Example

User: "Review PR 214." Its description says "retry failed webhooks up to 3 times".

  1. gh pr diff 214: 3 files, +120/-8. One reviewer.
  2. The reviewer reports a retry with no idempotency key. It proves it with a test that delivers the same webhook twice: two rows are written.
  3. You re-run that test: two rows. Report: "Blocker [correctness] webhook.go:58 - a retry writes a duplicate row. Proof: go test -run TestRetryTwice -> 2 rows, want 1." You don't post it until the user says so.

References

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at a0324a3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 3 weeks ago

README badge

README badge for avik-creator/agent-skills/review