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 a solid structure with an explicit 'Use when...' clause and covers the domain reasonably well. However, the capabilities listed lean toward aspirational outcomes ('catch bugs early', 'foster knowledge sharing') rather than concrete actions, and the trigger terms could be more comprehensive. The description also uses imperative voice ('Master effective...') rather than third person, though this is in the instructional framing rather than capability description.
Suggestions
Replace outcome-oriented language with concrete actions, e.g., 'Analyzes pull request diffs, identifies potential bugs and anti-patterns, suggests improvements, and drafts review comments.'
Expand trigger terms to include common variations like 'PR review', 'code feedback', 'review comments', 'approve changes', 'diff review', or 'CR'.
| 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 reads like a comprehensive code review training manual rather than a concise, actionable skill file. It contains substantial amounts of general knowledge Claude already possesses (feedback principles, common anti-patterns, communication techniques) and would benefit enormously from being trimmed to project-specific conventions and split into referenced sub-files. The code examples and checklists are its strongest elements, but they're buried in verbose explanatory text.
Suggestions
Cut content by 60-70%: Remove general advice Claude already knows (feedback principles, communication techniques, basic anti-patterns) and focus only on project-specific conventions, team-specific standards, or novel review workflows.
Split into multiple files: Move language-specific patterns to PYTHON_REVIEW.md and TS_REVIEW.md, security checklist to SECURITY_CHECKLIST.md, and templates to TEMPLATES.md, with clear one-level references from the main skill.
Add validation checkpoints to the review workflow: e.g., 'Before approving, verify all blocking items are resolved' or 'Run security scan tool X and confirm no new findings.'
Remove the 'When to Use This Skill' section — it's redundant with the YAML description and wastes tokens listing obvious use cases.
| 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 spelled out. Lists like 'Goals of Code Review' and 'Common Pitfalls' are textbook material Claude already has internalized. | 1 / 3 |
Actionability | Contains concrete code examples for language-specific patterns (Python mutable defaults, TypeScript error handling) and usable templates/checklists. However, much of the content is advisory/philosophical rather than executable guidance — it describes how to think about reviews rather than providing specific commands or tools to run. The checklists are actionable but the overall skill reads more like a training document than a task-oriented skill. | 2 / 3 |
Workflow Clarity | The four-phase review process (Context Gathering → High-Level → Line-by-Line → Summary) provides a clear sequence with time estimates. However, there are no validation checkpoints or feedback loops — no step says 'verify X before proceeding' or 'if Y fails, do Z.' The phases are more like guidelines than a rigorous workflow with explicit gates. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no references to external files. All content — language-specific patterns, security checklists, templates, advanced patterns — is inlined in a single massive document. Content like language-specific review 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
70444e5
- 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.