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 both what and when. However, the capabilities listed are more aspirational outcomes (catch bugs, foster knowledge sharing) than concrete actions, and the scope is broad enough to potentially overlap with debugging or mentoring skills. The description also uses imperative voice ('Master effective...') rather than third person, though this is in the lead-in rather than the action descriptions.
Suggestions
Replace outcome-oriented language with concrete actions, e.g., 'Analyzes pull request diffs, identifies code smells and bugs, suggests improvements, writes review comments, and creates review checklists.'
Add more natural trigger term variations such as 'PR review', 'code feedback', 'review comments', 'approve changes', 'diff review', or 'code quality'.
| 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 ('provide constructive feedback, catch bugs early, foster knowledge sharing while maintaining team morale') and when ('Use when reviewing pull requests, establishing review standards, or mentoring developers') with an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms 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, terms like 'mentoring developers' and 'catch bugs' could overlap with general coding assistance, debugging, or team management skills. The scope is somewhat broad covering practices, standards, and mentoring. | 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 excessively verbose guide to code review that reads more like a human training manual than an AI skill file. It explains many concepts Claude already knows (basic programming anti-patterns, feedback techniques, common vulnerabilities) and fails to leverage progressive disclosure by inlining everything into one massive document. The actionable workflow is present but buried in excessive supporting material.
Suggestions
Cut the content by 60-70%: Remove language-specific anti-patterns (Claude knows these), the sandwich method explanation, and general software engineering advice. Focus only on the review process, severity labels, and comment templates.
Extract checklists (security, performance, testing) and language-specific patterns into separate referenced files (e.g., 'See [SECURITY_CHECKLIST.md](SECURITY_CHECKLIST.md)') to enable progressive disclosure.
Reframe the skill as instructions for Claude specifically—what should Claude do when asked to review code, rather than teaching general code review philosophy to humans.
Add a validation step: after generating review comments, Claude should verify each comment is actionable, correctly categorized by severity, and references specific lines/code.
| 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). Much of this is general software engineering knowledge that doesn't need to be taught. The language-specific patterns sections are particularly wasteful—Claude knows about mutable default arguments, broad exception catching, and TypeScript's `any` type. | 1 / 3 |
Actionability | Provides concrete examples of good vs bad review comments and includes executable code snippets for language-specific patterns. However, much of the content is descriptive checklists and general advice rather than specific, executable guidance for Claude to follow when actually performing a code review. The skill reads more like a training document for human developers than actionable instructions for an AI agent. | 2 / 3 |
Workflow Clarity | The four-phase review process (Context Gathering → High-Level → Line-by-Line → Summary) provides a clear sequence, and the time estimates are helpful. However, there are no validation checkpoints or feedback loops—no guidance on what to do if issues are found during review phases, no explicit decision points for when to stop or escalate, and no verification that the review itself is complete or thorough. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no references to external files. The language-specific patterns, security checklists, advanced review patterns, and templates could all be split into separate referenced documents. Everything is inline, making the skill extremely long and difficult to navigate efficiently. | 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
27a7ed9
- 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.