code-review-excellence
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.
71
47%
Does it follow best practices?
Impact
85%
1.25xAverage score across 6 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/developer-essentials/skills/code-review-excellence/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description has good structural completeness with an explicit 'Use when...' clause and covers the domain adequately. However, the capabilities listed are more aspirational outcomes ('catch bugs early', 'foster knowledge sharing') than concrete actions, and the trigger terms could be expanded to cover more natural user phrasings. The description also uses imperative voice ('Master effective...') rather than third person, though this is in the instructional framing rather than capability statements.
Suggestions
Replace outcome-oriented language with concrete actions, e.g., 'Analyzes pull request diffs, identifies bugs and anti-patterns, suggests improvements, and generates review comments' instead of 'catch bugs early and foster knowledge sharing'.
Expand trigger terms in the 'Use when' clause to include common variations like 'PR review', 'code feedback', 'review comments', 'approve changes', or 'review checklist'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (code review) and some actions ('provide constructive feedback, catch bugs early, foster knowledge sharing'), but these are more like goals/outcomes than concrete specific actions. Compare to 'Extract text and tables from PDF files, fill forms, merge documents' which lists discrete operations. | 2 / 3 |
Completeness | Clearly answers both 'what' (effective code review practices for constructive feedback, catching bugs, knowledge sharing) and 'when' with an explicit 'Use when...' clause covering reviewing pull requests, establishing review standards, or mentoring developers. | 3 / 3 |
Trigger Term Quality | Includes some natural keywords like 'pull requests', 'code review', 'review standards', and 'mentoring developers', but misses common variations users might say such as 'PR review', 'code feedback', 'review comments', 'approve PR', or 'review checklist'. | 2 / 3 |
Distinctiveness Conflict Risk | While 'code review' and 'pull requests' are fairly specific, the description's mention of 'mentoring developers' and 'knowledge sharing' could overlap with general mentoring or team management skills. The scope is somewhat broad for a single skill. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a comprehensive but overly verbose guide to code review practices that explains many concepts Claude already knows well. It reads more like a developer training document than a concise skill file, with extensive coverage of basic programming anti-patterns, general communication advice, and review philosophy. The content would benefit significantly from aggressive trimming to focus only on novel, actionable guidance and splitting detailed reference material into separate files.
Suggestions
Cut content by 60-70%: Remove language-specific anti-patterns (Claude knows these), basic review philosophy, and communication advice. Focus on the severity labeling system, the review template, and the phased workflow as the core novel content.
Split into multiple files: Move language-specific patterns to PATTERNS.md, checklists to CHECKLISTS.md, and templates to TEMPLATES.md, with clear one-level references from the main SKILL.md.
Add validation checkpoints to the workflow: e.g., 'Before approving, verify all 🔴 blocking items are resolved' or 'If PR exceeds 400 lines, request split before reviewing.'
Make the skill more actionable by specifying exactly what Claude should output when asked to review code — e.g., a structured review format with severity labels, rather than general advice about how reviews should work.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Explains concepts Claude already knows well (what code review is, what good feedback looks like, basic Python/TypeScript anti-patterns, the sandwich method). Lists like 'Goals of Code Review' and 'Not the Goals' are common knowledge. The language-specific patterns section teaches basic programming pitfalls (mutable defaults, broad except clauses, using `any` in TypeScript) that Claude already knows thoroughly. | 1 / 3 |
Actionability | Provides concrete examples of good vs bad review comments, severity labels, and templates which are somewhat actionable. However, much of the content is descriptive guidance about how to think about reviews rather than executable instructions. The code examples are illustrative of anti-patterns rather than tools/commands Claude would execute. There are no specific tool invocations or automated workflows. | 2 / 3 |
Workflow Clarity | The four-phase review process (Context Gathering → High-Level → Line-by-Line → Summary) provides a clear sequence. However, there are no validation checkpoints or feedback loops — no step says 'verify X before proceeding' or 'if this fails, do Y.' The phases are more like checklists of things to think about rather than a rigorous workflow with explicit gates. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with no references to external files and no bundle files to support it. All content — from basic principles to language-specific patterns to advanced review patterns to templates — is crammed into a single file. Content like language-specific patterns, security checklists, and templates should be split into separate referenced files. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (530 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- wshobson/agents
- Commit
112197c
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.