Index of every page on this site: llms.txt
All skills
wshobson avatar

/code-review-excellence

@4220308
by Seth Hobsonwshobson/agents43k stars
4,518
Run it yourself

Master effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing review standards, or mentoring developers.

Use this Skill: https://skilld.dev/gh/wshobson/agents/code-review-excellence

Nothing lands on disk. Nothing to clean up.

Fork this Skill

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

SKILL.md

≈66 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈1.7k more on demand in 2 files.

Description uses 3.3% 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 ≈265 characters, or 3.3%.

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.

Code Review Excellence

Transform code reviews from gatekeeping to knowledge sharing through constructive feedback, systematic analysis, and collaborative improvement.

When to Use This Skill

  • Reviewing pull requests and code changes
  • Establishing code review standards for teams
  • Mentoring junior developers through reviews
  • Conducting architecture reviews
  • Creating review checklists and guidelines
  • Improving team collaboration
  • Reducing code review cycle time
  • Maintaining code quality standards

Core Principles

1. The Review Mindset

Goals of Code Review:

  • Catch bugs and edge cases
  • Ensure code maintainability
  • Share knowledge across team
  • Enforce coding standards
  • Improve design and architecture
  • Build team culture

Not the Goals:

  • Show off knowledge
  • Nitpick formatting (use linters)
  • Block progress unnecessarily
  • Rewrite to your preference

2. Effective Feedback

Good Feedback is:

  • Specific and actionable
  • Educational, not judgmental
  • Focused on the code, not the person
  • Balanced (praise good work too)
  • Prioritized (critical vs nice-to-have)
❌ Bad: "This is wrong."
✅ Good: "This could cause a race condition when multiple users
access simultaneously. Consider using a mutex here."

❌ Bad: "Why didn't you use X pattern?"
✅ Good: "Have you considered the Repository pattern? It would
make this easier to test. Here's an example: [link]"

❌ Bad: "Rename this variable."
✅ Good: "[nit] Consider `userCount` instead of `uc` for
clarity. Not blocking if you prefer to keep it."

3. Review Scope

What to Review:

  • Logic correctness and edge cases
  • Security vulnerabilities
  • Performance implications
  • Test coverage and quality
  • Error handling
  • Documentation and comments
  • API design and naming
  • Architectural fit

What Not to Review Manually:

  • Code formatting (use Prettier, Black, etc.)
  • Import organization
  • Linting violations
  • Simple typos

Review Process

Phase 1: Context Gathering (2-3 minutes)

Before diving into code, understand:

1. Read PR description and linked issue
2. Check PR size (>400 lines? Ask to split)
3. Review CI/CD status (tests passing?)
4. Understand the business requirement
5. Note any relevant architectural decisions

Phase 2: High-Level Review (5-10 minutes)

1. **Architecture & Design**
   - Does the solution fit the problem?
   - Are there simpler approaches?
   - Is it consistent with existing patterns?
   - Will it scale?

2. **File Organization**
   - Are new files in the right places?
   - Is code grouped logically?
   - Are there duplicate files?

3. **Testing Strategy**
   - Are there tests?
   - Do tests cover edge cases?
   - Are tests readable?

Phase 3: Line-by-Line Review (10-20 minutes)

For each file:

1. **Logic & Correctness**
   - Edge cases handled?
   - Off-by-one errors?
   - Null/undefined checks?
   - Race conditions?

2. **Security**
   - Input validation?
   - SQL injection risks?
   - XSS vulnerabilities?
   - Sensitive data exposure?

3. **Performance**
   - N+1 queries?
   - Unnecessary loops?
   - Memory leaks?
   - Blocking operations?

4. **Maintainability**
   - Clear variable names?
   - Functions doing one thing?
   - Complex code commented?
   - Magic numbers extracted?

Phase 4: Summary & Decision (2-3 minutes)

1. Summarize key concerns
2. Highlight what you liked
3. Make clear decision:
   - ✅ Approve
   - 💬 Comment (minor suggestions)
   - 🔄 Request Changes (must address)
4. Offer to pair if complex

Before writing review feedback, read references/review-techniques.md for checklists, question framing, collaboration, and severity techniques.

Before language-specific, architectural, test-quality, or security review, read references/review-patterns.md for review patterns and checklists.

Giving Difficult Feedback

Pattern: The Sandwich Method (Modified)

Traditional: Praise + Criticism + Praise (feels fake)

Better: Context + Specific Issue + Helpful Solution

Example:
"I noticed the payment processing logic is inline in the
controller. This makes it harder to test and reuse.

[Specific Issue]
The calculateTotal() function mixes tax calculation,
discount logic, and database queries, making it difficult
to unit test and reason about.

[Helpful Solution]
Could we extract this into a PaymentService class? That
would make it testable and reusable. I can pair with you
on this if helpful."

Handling Disagreements

When author disagrees with your feedback:

1. **Seek to Understand**
   "Help me understand your approach. What led you to
   choose this pattern?"

2. **Acknowledge Valid Points**
   "That's a good point about X. I hadn't considered that."

3. **Provide Data**
   "I'm concerned about performance. Can we add a benchmark
   to validate the approach?"

4. **Escalate if Needed**
   "Let's get [architect/senior dev] to weigh in on this."

5. **Know When to Let Go**
   If it's working and not a critical issue, approve it.
   Perfection is the enemy of progress.

Best Practices

  1. Review Promptly: Within 24 hours, ideally same day
  2. Limit PR Size: 200-400 lines max for effective review
  3. Review in Time Blocks: 60 minutes max, take breaks
  4. Use Review Tools: GitHub, GitLab, or dedicated tools
  5. Automate What You Can: Linters, formatters, security scans
  6. Build Rapport: Emoji, praise, and empathy matter
  7. Be Available: Offer to pair on complex issues
  8. Learn from Others: Review others' review comments

Common Pitfalls

  • Perfectionism: Blocking PRs for minor style preferences
  • Scope Creep: "While you're at it, can you also..."
  • Inconsistency: Different standards for different people
  • Delayed Reviews: Letting PRs sit for days
  • Ghosting: Requesting changes then disappearing
  • Rubber Stamping: Approving without actually reviewing
  • Bike Shedding: Debating trivial details extensively

Templates

PR Review Comment Template

## Summary

[Brief overview of what was reviewed]

## Strengths

- [What was done well]
- [Good patterns or approaches]

## Required Changes

🔴 [Blocking issue 1]
🔴 [Blocking issue 2]

## Suggestions

💡 [Improvement 1]
💡 [Improvement 2]

## Questions

❓ [Clarification needed on X]
❓ [Alternative approach consideration]

## Verdict

✅ Approve after addressing required changes

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 alerts1mo5 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill is an educational resource providing best practices, checklists, and techniques for conducting effective code reviews. It contains no executable code, network operations, or sensitive data access.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

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

Last checked against GitHub 3 days ago.

Activeupdated last month
  • code-review
  • pull-requests
  • feedback
  • mentoring
  • best-practices
  • team-collaboration
  • quality-assurance
  • architecture-review

README badge

README badge for wshobson/agents/code-review-excellence

Provides methods and frameworks for conducting effective code reviews: giving constructive feedback, catching bugs and security issues, organizing review processes by phase, and handling difficult feedback or disagreements. Covers language-specific patterns for Python and TypeScript, review checklists, and techniques for architectural and security reviews.

Generated from the current SKILL.md.

Does this skill apply to all programming languages?
The skill covers general review principles applicable to any language, with detailed examples for Python and TypeScript/JavaScript. The core techniques (checklist method, question approach, severity labeling) work across all languages.
What's the recommended PR size for review?
The skill recommends 200-400 lines max per PR for effective review. PRs larger than 400 lines should be asked to split into smaller changes.
Does this cover security code reviews?
Yes. The skill includes a dedicated security review checklist covering authentication, authorization, input validation, data protection, and common vulnerabilities like SQL injection and XSS.
How should I structure feedback when reviewing code?
The skill recommends using severity labels (blocking, important, nit, suggestion, learning, praise) and the question approach rather than commands, paired with specific, actionable suggestions tied to concrete problems.
What should I focus on and what should automated tools handle?
Focus on logic correctness, security, performance, design fit, and testing quality. Don't manually review formatting, imports, linting violations, or typos—use Prettier, Black, and linters for those.

Generated from the current SKILL.md. These answers refresh after source changes.