Skip to content

About

A skill encoding a principled, battle-tested methodology for code review - both for reviewing changes and for getting your own changes through review.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Code Review Craft

A Claude skill that encodes a principled, battle-tested methodology for code review — both for reviewing changes and for getting your own changes through review well.

It's not a checklist. It teaches Claude the philosophy (the central principle: favor approving a change once it definitely improves code health, even if it isn't perfect) and the operational habits that follow from it — what to look for, how to comment, how to handle pushback, how to write a description, how to size a change.

What it does

When this skill is active, Claude becomes useful in several common situations:

  • Reviewing a diff, PR, patch, or commit — Claude walks the three-pass review (broad view → main parts → the rest), weighs the right dimensions (design, functionality, complexity, tests, naming, comments, style, docs), flags concurrency hazards and over-engineering, and writes comments with severity labels (Nit:, Optional:, FYI:) so authors know what's blocking and what's not.
  • Writing commit / PR / CL descriptions — short, imperative first line; a body that explains why, not just what; enough context to survive dead links.
  • Sizing and splitting changes — when a diff is too big to review well, Claude suggests concrete splits (stacking, by files, horizontal, vertical) instead of vague "make it smaller" advice.
  • Replying to reviewer comments — collaborative rather than defensive, fixing the code when a reviewer was confused (not just explaining in the review tool).
  • Handling urgent changes — distinguishes genuine emergencies from soft deadlines and applies relaxed rigor only when truly warranted.

It triggers automatically on natural phrasing ("take a look at this PR," "write a commit message for this," "this change is huge, help me break it up") — no need to invoke it explicitly.

Install in Claude.ai (web or desktop)

  1. Settings → Capabilities — make sure Code execution and file creation is on. Skills won't work without it.
  2. Customize → Skills — click +, choose Upload a skill.
  3. Upload code-review-craft.skill (the pre-built file in this repo) — or zip the SKILL.md plus the references/ folder yourself and upload that zip.
  4. Toggle it on. Done.

If your uploader refuses the .skill extension, rename it to .zip. Same bytes.

Install in Claude Code

Clone or copy this repo's content into one of:

.claude/skills/code-review-craft/      # project-scoped
~/.claude/skills/code-review-craft/    # user-scoped (works in every repo)

You only need SKILL.md and the references/ folder for the skill to function — the README.md, LICENSE, and .gitignore are repo metadata.

Repository layout

code-review-craft/
├── SKILL.md                          # Dispatcher: philosophy + routing + quick-starts
├── references/
│   ├── reviewing-changes.md          # Full reviewer's guide
│   ├── authoring-changes.md          # Full author's guide
│   └── emergencies.md                # Hotfix / urgent change handling
├── code-review-craft.skill           # Pre-packaged skill, ready to upload
├── README.md
├── LICENSE                           # CC-BY 3.0
└── .gitignore

Reference files are loaded by Claude only when needed (progressive disclosure), so the philosophy and quick-starts live in SKILL.md and the depth lives next door.

Origin and attribution

The substance of this skill is adapted from google/eng-practices, Google's published engineering practices documentation — specifically the code review guidelines (both the reviewer's guide and the change author's guide) and the emergencies guidance. That material is licensed under Creative Commons Attribution 3.0 Unported (CC-BY 3.0). The original is the collective experience of many Google engineers over many years; this skill restates and condenses it into a form Claude can apply directly during a review.

Changes made in adapting the original:

  • Reframed as imperative operational guidance for an AI assistant rather than human-facing documentation.
  • Restructured as a dispatcher (SKILL.md) with three depth references loaded on demand.
  • Condensed prose and reorganized headings for the new format.
  • Substantive content (the principles, the dimensions, the comment conventions, the emergencies criteria) is preserved.

License

This skill is distributed under the same license as the original: CC-BY 3.0. See LICENSE for the full text.

In short: you may share and adapt the material, including for commercial purposes, as long as you give appropriate credit, link to the license, and indicate whether changes were made. You may not imply endorsement by Google or by anyone else.

About

A skill encoding a principled, battle-tested methodology for code review - both for reviewing changes and for getting your own changes through review.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors