Use this skill when the user asks to review their local git changes, staged or unstaged diffs, or wants a code review before committing. Triggers on "review my changes", "review staged", "review my diff", "check my code", "code review local changes", "review unstaged", "review before commit".
Instrucciones de origen · Vista previa de solo lectura
name
code-review-mastery
version
0.2.0
description
Use this skill when the user asks to review their local git changes, staged or unstaged diffs, or wants a code review before committing. Triggers on "review my changes", "review staged", "review my diff", "check my code", "code review local changes", "review unstaged", "review before commit".
When this skill is activated, always start your first response with the 🧢 emoji.
Local Diff Code Review
This skill reviews your local git changes (staged or unstaged) with
project-aware analysis. It gathers project context - lint rules, conventions,
framework patterns - then produces structured [MAJOR] / [MINOR] findings
you can work through interactively.
When to use this skill
Trigger this skill when the user:
Asks to review their local changes, staged changes, or unstaged changes
Says "review my diff", "check my code", "code review before commit"
Wants a quality check on what they're about to commit or push
Asks "what's wrong with my changes" or "anything I should fix before committing"
Do NOT trigger this skill for:
Reviewing remote PRs or GitHub links (use a PR review tool instead)
Writing or refactoring code from scratch
Architecture discussions not tied to a specific set of changes
General code quality advice without a concrete diff to review
Key principles
Review the code, not the person - Findings are about the change, not
the author. Frame issues as observations, not judgments.
Prioritize by impact - Security > Correctness > Performance > Design >
Readability > Convention. Spend most analysis time at the top of this list.
Two-tier severity - Every finding is either [MAJOR] (must fix) or
[MINOR] (consider fixing). No ambiguity, no middle ground.
Respect project conventions - Read configs and surrounding code before
judging. What looks wrong in isolation may be the project's established
pattern.
Present, don't preach - Structured findings with file locations and
suggested fixes. Not essays about best practices.
[MAJOR] vs [MINOR] definitions
Severity
Criteria
Examples
[MAJOR]
Must be fixed. Would block a PR in a professional code review.
Bugs, security vulnerabilities, data loss risks, missing error handling for critical paths, violations of explicit project rules (lint configs, CLAUDE.md), missing tests for new behavior
[MINOR]
Improves quality but code works without it. Reviewer would approve anyway.
Deviates from naming convention in surrounding files
Import style inconsistent with project pattern
Breaks a rule stated in CLAUDE.md or AGENT.md
Testing ([MAJOR] for missing tests)
New behavior without corresponding tests
Tests that don't assert meaningful behavior
Skipped tests without explanation
Test names that don't describe the behavior being verified
Output format specification
Use this exact structure for the review output:
## Code Review: [staged|unstaged] changes
**Files changed**: N | **Insertions**: +X | **Deletions**: -Y
### [MAJOR] Issues (N)
- [ ] **file.ts:42** [Security] Description of the issue.
Suggested fix or approach.
- [ ] **file.ts:87** [Correctness] Description of the issue.
Suggested fix or approach.
### [MINOR] Suggestions (N)
- [ ] **file.ts:15** [Readability] Description of the suggestion.
Suggested improvement.
- [ ] **file.ts:99** [Convention] Description of the deviation.
Project convention reference.
### Summary
N major issues to resolve, M minor suggestions to consider.
Would you like me to fix any of these? Tell me which items or say "fix all MAJOR" / "fix all".
Rules for the output:
Group all [MAJOR] findings first, then all [MINOR] findings
Within each group, order by file path, then line number
Each finding is a checkbox (- [ ]) so the user can track progress
Inform user "No local changes to review." and stop.
Mixed staged/unstaged
Ask user: "You have both staged and unstaged changes. Which would you like me to review? (staged / unstaged / both)"
Merge conflicts
Note conflict markers as [MAJOR] and suggest resolving before review.
Only deletions
Review for missing cleanup (dangling references, broken imports, orphaned tests).
Anti-patterns
Avoid these mistakes when producing a review:
Anti-pattern
Why it's wrong
What to do instead
Flagging what linters already catch
Wastes attention if CI enforces the rule
Check if a linter config exists and CI runs it; skip those findings
Ignoring CLAUDE.md / project conventions
Misses the project's actual standards
Always read project configs in Phase 2 before analyzing
Writing essay-length findings
Hard to action, loses signal in noise
One-line description + one-line suggested fix per finding
Marking style preferences as [MAJOR]
Erodes trust in severity classification
Only [MAJOR] for bugs, security, explicit rule violations, missing tests
Reviewing files not in the diff
Scope creep; confuses the user
Only analyze lines present in the diff output
Inventing project rules
Flagging violations of standards the project doesn't have
Only flag Convention [MAJOR] when you found an explicit config/rule
Skipping the offer to fix
Misses the interactive value of this skill
Always end with the fix offer
Gotchas
Reviewing files not in the diff - It's easy to open related files for context and then accidentally include findings from those files in the review. Only report issues on lines that appear in the actual diff output - scope creep confuses authors and erodes trust.
Flagging what linters already enforce - If the project has ESLint, Prettier, or Ruff configured and CI runs them, reporting style violations in the review duplicates automated feedback. Check for linter configs in Phase 2 and skip findings that existing tooling will catch.
Severity inflation - Marking every finding [MAJOR] to signal thoroughness causes authors to lose trust in severity ratings and start ignoring the review. Apply the staff engineer test strictly: only block-worthy issues are [MAJOR]. When in doubt, downgrade to [MINOR].
Missing context before judging - A pattern that looks wrong in isolation (e.g., a .catch(() => {}) that swallows errors) may be intentional and documented elsewhere. Phase 2 context gathering exists to prevent false positives. Read CLAUDE.md, surrounding files, and lint config before flagging anything as a violation.
Large diff, no focus strategy - Reviewing a 1,000-line diff end-to-end produces an overwhelming output that authors can't action. For large diffs, warn the user and focus exclusively on [MAJOR] findings. Offer to do a second pass for [MINOR] items if wanted.
References
For detailed content on specific topics, read the relevant file from references/:
references/review-checklist.md - Full per-category review checklist with
detailed items for correctness, security, performance, readability, testing,
documentation, and convention checks
references/context-detection.md - Guide for gathering project context
before reviewing: config file detection, framework heuristics, convention
sampling, and language-specific focus areas
Load references/review-checklist.md when performing a thorough multi-pass
review. Load references/context-detection.md when the project uses an
unfamiliar framework or you need to identify conventions systematically.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
