Skip to main content
skill CX Codex

code-review-playbook — Claude Code skill: setup and usage

code-review-playbook supplies structured review workflows, conventional comment formats, and security checklists. Triggers during pull request evaluations or author self-reviews.

MIT 254 installs ★ 305 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill code-review-playbook -a claude-code
Open on GitHub

What code-review-playbook does

This skill supplies explicit guidelines for inspecting source code and structuring peer feedback. It includes quality checklists checking function length under 50 lines, cyclomatic complexity below 10, naming readability, and duplication. Security checks target missing endpoint authentication, unsanitized inputs vulnerable to injection, and hardcoded API tokens.

Feedback follows the Conventional Comments standard, using labels like issue, suggestion, praise, or security alongside blocking decorations. The skill runs on Haiku and restricts active capabilities to Read, Glob, Grep, WebFetch, and WebSearch.

Direct user invocation is disabled (user-invocable: false), and compatibility targets Claude Code 2.1.277+. Performing an automated end-to-end pull request audit requires the separate ork:review-pr workflow instead.

What it helps with

  • standardize pull request feedback with conventional comments formatting
  • verify changed files against baseline security and injection checks
  • enforce limits on function length and cyclomatic complexity
  • conduct structured self-review passes before requesting team feedback

Example prompts for the agent

  • Review the current git diff using the code-review-playbook checklist
  • Format these code findings into conventional comments with blocking tags
  • Run the security checklist against the modified authentication routes

How to install code-review-playbook

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill code-review-playbook -a claude-code

2Manually: put the files in place

~/.claude/skills/code-review-playbook/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/code-review-playbook/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about code-review-playbook

How to install code-review-playbook in Claude Code?

Run npx skills add yonatangross/orchestkit --skill code-review-playbook -a claude-code in your project terminal.

What does code-review-playbook do?

It equips the agent with guidelines for PR reviews, standardizing comment formats and quality checklists across logic and security.

How does this differ from review-pr?

This skill acts as a methodology reference and checklist guide, while ork:review-pr handles full multi-agent PR reviews.

Source text

SKILL.md · MIT
---
name: code-review-playbook
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Review process, conventional comments, language checklists and feedback templates. Use when reviewing code or standardizing review practice. To review a PR end to end, use review-pr."
context: inherit
user-invocable: false
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/pattern-consistency-enforcer"
effort: low
model: haiku
metadata:
  category: document-asset-creation
  version: "2.0.0"
  author: "OrchestKit"
  complexity: "low"
  tags: "code-review, quality, collaboration, best-practices, testing"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
---

# Code Review Playbook
This skill provides a comprehensive framework for effective code reviews that improve code quality, share knowledge, and foster collaboration. Whether you're a reviewer giving feedback or an author preparing code for review, this playbook ensures reviews are thorough, consistent, and constructive.

## Overview
- Reviewing pull requests or merge requests
- Preparing code for review (self-review)
- Establishing code review standards for teams
- Training new developers on review best practices
- Resolving disagreements about code quality
- Improving review processes and efficiency

## Upstream coverage (do not restate)

This skill is a thin wrapper. General review craft is documented first-party elsewhere;
only OrchestKit's own decisions live here. Load `Read("references/ork-delta.md")`
for the house rules that survived the retired files.

| Topic | Go here instead |
|-------|-----------------|
| Review philosophy, speed, tone, PR sizing | https://google.github.io/eng-practices/review/ |
| Conventional comment labels and decorations | `references/conventional-comments.md`, https://conventionalcomments.org/ |
| OWASP Top 10 review checks | `rules/security-baseline.md`, https://owasp.org/Top10/ |
| Generic language and framework review checklists | `rules/typescript-quality.md`, `rules/python-quality.md`, `rules/linting-biome-rules.md` |
| Review report shape and multi-agent full-PR review | `ork:review-pr` |
| Applying findings to the working tree | `/code-review --fix`, `/simplify` (see below) |
| Security-only pass over the current branch | `/security-review` |
| GitHub review mechanics (approve, request changes, inline comments) | https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests |

---

## Conventional Comments

```
issue [blocking]: Missing error handling for API call
If the API returns a 500 error, this will crash. Add try/catch.

security [blocking]: API endpoint is not authenticated
The /api/admin/users endpoint is missing auth middleware.
```

Load `Read("references/conventional-comments.md")` for the full format, labels (praise, nitpick, suggestion, issue, question, security, bug, breaking), decorations ([blocking], [non-blocking], [if-minor]), and examples.

---

## Review Process

### 1. Before Reviewing

**Check Context:**
- Read the PR/MR description
- Understand the purpose and scope
- Review linked tickets or issues
- Check CI/CD pipeline status

**Verify Automated Checks:**
- [ ] Tests are passing
- [ ] Linting has no errors
- [ ] Type checking passes
- [ ] Code coverage meets targets
- [ ] No merge conflicts

**Set Aside Time:**
- Small PR (< 200 lines): 15-30 minutes
- Medium PR (200-500 lines): 30-60 minutes
- Large PR (> 500 lines): 1-2 hours (or ask to split)

### 2. During Review

**Follow a Pattern:**

1. **High-Level Review** (5-10 minutes)
   - Read PR description and understand intent
   - Skim all changed files to get overview
   - Verify approach makes sense architecturally
   - Check that changes align with stated purpose

2. **Detailed Review** (20-45 minutes)
   - Line-by-line code review
   - Check logic, edge cases, error handling
   - Verify tests cover new code
   - Look for security vulnerabilities
   - Ensure code follows team conventions

3. **Testing Considerations** (5-10 minutes)
   - Are tests comprehensive?
   - Do tests test the right things?
   - Are edge cases covered?
   - Is test data realistic?

4. **Documentation Check** (5 minutes)
   - Are complex sections commented?
   - Is public API documented?
   - Are breaking changes noted?
   - Is README updated if needed?

### 3. After Reviewing

**Provide Clear Decision:**
- ✅ **Approve**: Code is ready to merge
- 💬 **Comment**: Feedback provided, no action required
- 🔄 **Request Changes**: Issues must be addressed before merge

**Respond to Author:**
- Answer questions promptly
- Re-review after changes made
- Approve when issues resolved
- Thank author for addressing feedback

---

## Review Checklists

### General Code Quality

- [ ] **Readability**: Code is easy to understand
- [ ] **Naming**: Variables and functions have clear, descriptive names
- [ ] **Comments**: Complex logic is explained
- [ ] **Formatting**: Code follows team style guide
- [ ] **DRY**: No unnecessary duplication
- [ ] **SOLID Principles**: Code follows SOLID where applicable
- [ ] **Function Size**: Functions are focused and < 50 lines
- [ ] **Cyclomatic Complexity**: Functions have complexity < 10

### Security

- [ ] **Authentication**: Protected endpoints require auth
- [ ] **Authorization**: Users can only access their own data
- [ ] **Input Sanitization**: SQL injection, XSS prevented
- [ ] **Secrets Management**: No hardcoded credentials or API keys
- [ ] **Encryption**: Sensitive data encrypted at rest and in transit
- [ ] **Rate Limiting**: Endpoints protected from abuse

---

## Quick Start Guide

**For Reviewers:**
1. Read PR description and understand intent
2. Check that automated checks pass
3. Do high-level review (architecture, approach)
4. Do detailed review (logic, edge cases, tests)
5. Use conventional comments for clear communication
6. Provide decision: Approve, Comment, or Request Changes

**For Authors:**
1. Write clear PR description
2. Perform self-review before requesting review
3. Ensure all automated checks pass
4. Keep PR focused and reasonably sized (< 400 lines)
5. Respond to feedback promptly and respectfully
6. Make requested changes or explain reasoning

---

## CC Built-in Review Commands (2.1.152+)

This playbook is the manual framework; Claude Code ships built-in commands that automate parts of it:

- **`/code-review`** — reviews the current diff for correctness bugs and reuse/simplification/efficiency cleanups.
- **`/code-review --fix`** (CC 2.1.152+) — runs the review then applies the findings to your working tree (a bug-hunting review covering correctness plus reuse/simplification/efficiency).
- **`/code-review --comment`** — posts findings as inline PR comments.
- **`/simplify`** — **CC 2.1.154 changed this**: it now runs a **cleanup-only** review (reuse, simplification, efficiency, altitude) and applies the fixes — it no longer invokes the full `/code-review --fix` bug-hunt. Reach for `/simplify` for tidy-ups, `/code-review --fix` for bug-finding-plus-fix.

Use the built-ins for fast diff-scoped passes; use `ork:review-pr` for the multi-agent, full-PR review (security + testing + architecture).

---

**Skill Version**: 2.0.0
**Last Updated**: 2026-01-08
**Maintained by**: OrchestKit

## Related Skills

- `ork:architecture-patterns` - Enforce testing and architectural best practices during code review
- `ork:security-patterns` - Auth, input validation, and OWASP patterns to complement manual review
- `ork:testing-unit` - Unit testing patterns to verify during review

## Rules

Each category has individual rule files in `rules/` loaded on-demand:

| Category | Rule | Impact | Key Pattern |
|----------|------|--------|-------------|
| TypeScript Quality | `rules/typescript-quality.md` | HIGH | No `any`, Zod validation, exhaustive switches, React 19 |
| Python Quality | `rules/python-quality.md` | HIGH | Pydantic v2, ruff, mypy strict, async timeouts |
| Security Baseline | `rules/security-baseline.md` | CRITICAL | No secrets, auth on endpoints, input validation |
| Linting | `rules/linting-biome-setup.md` | HIGH | Biome setup, ESLint migration, gradual adoption |
| Linting | `rules/linting-biome-rules.md` | HIGH | Biome config, type-aware rules, CI integration |

**Total: 5 rules across 4 categories**

## Available Scripts

- **`scripts/review-pr.md`** - Dynamic PR review with auto-fetched GitHub data
  - Auto-fetches: PR title, author, state, changed files, diff stats, comments count
  - Usage: `review-pr [PR-number]`
  - Requires: GitHub CLI (`gh`)
  - Uses `$ARGUMENTS` and `!command` for live PR data

- **`assets/pr-template.md`** - PR description template

There is deliberately no review-report template here; `ork:review-pr` owns that output
shape. See `references/ork-delta.md`.

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Code review and refactoring →

From the same set86

The whole set →
distributed-systems distributed-systems is a Claude Code skill with architectural guidelines for distributed locks, circuit breakers, idempotency keys, and rate limiting. CX Codex +1 297installs monitoring-observability monitoring-observability — a skill for Claude Code that configures Prometheus metrics, Grafana dashboards, and Langfuse v4 tracing. Activates when adding logging, distributed tracing, or LLM cost tracking. CX Codex +1 270installs vite-advanced vite-advanced is a Claude Code and Codex skill for Vite 8 builds with Rolldown, chunk splitting, and Environment API. It activates when editing vite.config.* or files under **/vite/**. CX Codex +1 265installs quality-gates quality-gates scores task complexity on a 1–5 scale and halts work when requirements are vague or solutions loop. Triggers before complex tasks and after repeated failures. CX Codex +1 259installs python-backend python-backend — a skill for Claude Code and Codex providing async Python patterns when editing *.py or package files. Enforces conventions for FastAPI, SQLAlchemy 2.0, and asyncio. CX Codex +1 250installs accessibility accessibility — a Claude Code skill for building accessible web interfaces. It activates for work on screen reader support, keyboard navigation, focus handling, and ARIA components. CX Codex +1 246installs memory-fabric memory-fabric is a Claude Code skill that orchestrates knowledge graph retrieval, parses queries, deduplicates facts, and ranks results. It runs when designing or debugging agent memory mechanics. CX Codex +1 244installs multimodal-llm multimodal-llm — a skill for Claude Code and Codex that routes tasks across vision, speech, and video models. The agent activates it when handling image analysis, audio transcription, or video generation APIs. CX Codex +1 243installs

Project sponsors

Companies that keep this analytics open