jbvc/clean-code
Applies principles from Robert C. Martin's 'Clean Code'. Use this skill when writing, reviewing, or refactoring code to ensure high quality, readability, and maintainability. Covers naming, functions, comments, error handling, and class design.
55
55%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
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 this skill when...' clause and covers both what and when. However, it lists topic categories rather than specific concrete actions, and its broad applicability to any code writing/reviewing scenario creates potential overlap with other coding skills. Adding more specific actions and distinguishing triggers would strengthen it.
Suggestions
Replace category names with concrete actions, e.g., 'Enforces meaningful naming conventions, extracts small single-purpose functions, removes redundant comments, applies proper error handling patterns, and designs cohesive classes.'
Add more natural trigger terms users might say, such as 'code quality', 'code smells', 'SOLID principles', 'technical debt', or 'best practices'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (clean code principles) and lists some areas covered (naming, functions, comments, error handling, class design), but these are categories rather than concrete actions. It doesn't specify what it actually does with these areas (e.g., 'enforces single-responsibility functions', 'suggests meaningful variable names'). | 2 / 3 |
Completeness | Clearly answers both 'what' (applies Clean Code principles covering naming, functions, comments, error handling, class design) and 'when' (when writing, reviewing, or refactoring code to ensure quality, readability, and maintainability). The 'Use this skill when...' clause is explicit. | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'Clean Code', 'refactoring', 'readability', 'maintainability', 'naming', 'error handling', but misses common natural terms users might say like 'code quality', 'code smell', 'best practices', 'SOLID principles', or 'technical debt'. | 2 / 3 |
Distinctiveness Conflict Risk | The reference to Robert C. Martin's 'Clean Code' provides some distinctiveness, but the broad scope of 'writing, reviewing, or refactoring code' could easily overlap with general code review skills, linting skills, or other coding best-practice skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
22%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads as a condensed summary of Robert C. Martin's 'Clean Code' book rather than an actionable skill for Claude. It restates well-known programming principles that Claude already knows, without providing concrete workflows, executable examples, or specific decision procedures. The content would be significantly more valuable if it focused on specific refactoring patterns, code review checklists with concrete before/after examples, and step-by-step workflows for applying these principles.
Suggestions
Replace the book summary format with concrete, executable workflows: e.g., 'When reviewing code: 1. Check function length (>20 lines → extract), 2. Check naming (apply these specific patterns), 3. Check error handling (replace null returns with exceptions)' with before/after code examples for each step.
Remove content Claude already knows (basic Clean Code principles, TDD laws, FIRST principles) and focus on project-specific conventions or non-obvious applications that add genuine value.
Add concrete before/after refactoring examples with executable code showing the transformation, not just naming the principle.
Define a clear step-by-step workflow for the three use cases (writing new code, reviewing PRs, refactoring legacy code) with explicit validation checkpoints.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill summarizes a well-known book that Claude already knows extensively. While it's reasonably organized, much of this is restating principles Claude is already deeply familiar with (Clean Code is canonical programming knowledge). The 'When to Use' section and core philosophy quote add little value. | 2 / 3 |
Actionability | The content is almost entirely descriptive principles and guidelines rather than concrete, executable guidance. There's one small Python example in the Comments section, but no actionable code patterns, refactoring recipes, or specific commands. It reads like a book summary, not an instruction set Claude can execute. | 1 / 3 |
Workflow Clarity | There is no clear workflow or sequenced process for applying these principles. The checklist at the end is a start but lacks any process for how to actually perform a code review or refactoring session. For a skill covering reviewing and refactoring code, there should be step-by-step workflows with validation checkpoints. | 1 / 3 |
Progressive Disclosure | The content is organized into numbered sections with clear headers, which aids navigation. However, it's a monolithic document with no references to external files for deeper content, and some sections (like Smells and Heuristics) are too terse to be useful while others could be split out for detail. | 2 / 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 |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents