clean-code

This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean."

Quality

31%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/clean-code/SKILL.md

The canonical home for this skill is clean-code in sickn33/agentic-awesome-skills

Quality

Content

22%Scale 1-3

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 lacks concrete workflows, executable examples, and specific instructions for how Claude should apply these principles when transforming code. Claude already knows these principles, so the skill adds minimal new operational value.

Suggestions

Add a concrete step-by-step workflow for how Claude should approach a code cleanup task (e.g., 1. Identify smells, 2. Extract functions, 3. Rename variables, 4. Verify tests pass), with validation checkpoints.

Include before/after code examples showing complete, executable transformations rather than just naming principles — e.g., a full function refactored from 'dirty' to 'clean' with annotations.

Remove content Claude already knows (the book summary aspects) and focus on project-specific conventions, thresholds, or preferences that differ from defaults — e.g., 'In this codebase, max function length is 15 lines' or 'Prefer X pattern over Y'.

Add actionable instructions for how Claude should respond when asked to review or refactor code — what format to use, what to prioritize, and how to present changes.

Dimension	Reasoning	Score
Conciseness	The skill summarizes Clean Code principles that Claude already knows well. The opening philosophy quote, 'When to Use' section, and many of the bullet points are things Claude would already understand. However, the content is reasonably organized and not excessively padded — it's more of a reference card than a verbose explanation.	2 / 3
Actionability	The skill is almost entirely descriptive principles and guidelines rather than concrete, executable instructions. There's one small Python example in the Comments section, but no actionable workflow for how Claude should actually transform code. It reads like a book summary, not an operational skill.	1 / 3
Workflow Clarity	There is no clear workflow or sequence of steps for Claude to follow when applying clean code principles. The checklist at the end is a start but lacks any process for how to approach a refactoring task, what order to apply changes, or how to validate improvements.	1 / 3
Progressive Disclosure	The content is well-structured with clear numbered sections and headers, making it easy to scan. However, it's a monolithic document with no references to external files for deeper dives, and some sections (like Smells and Heuristics) are too terse to be useful while others could be split out.	2 / 3
	Total	6 / 12 Passed

Description

40%Scale 1-3

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 relies heavily on the book title 'Clean Code' as a shorthand rather than spelling out concrete capabilities or explicit trigger conditions. It lacks specific actions (e.g., refactoring, naming improvements, reducing function length) and natural user-facing keywords. The 'Use it to' clause is too abstract to serve as a reliable trigger for skill selection.

Suggestions

List specific concrete actions the skill performs, e.g., 'Refactors functions for single responsibility, improves variable/function naming, reduces code duplication, simplifies complex conditionals.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks to refactor code, improve readability, fix code smells, apply clean code principles, or review code quality.'

Include common keyword variations users might say, such as 'refactor', 'code review', 'readability', 'maintainability', 'code smell', 'naming conventions', 'SOLID principles'.

Dimension	Reasoning	Score
Specificity	The description mentions no concrete actions—'transform code that works into code that is clean' is abstract and metaphorical. It does not list specific capabilities like refactoring functions, renaming variables, reducing complexity, etc.	1 / 3
Completeness	It has a weak 'what' (transform code into clean code) and a 'Use it to...' clause, but the 'when' is vague—it doesn't specify explicit triggers like 'use when the user asks for code review, refactoring, or improving readability.' The 'what' and 'when' are both underspecified.	2 / 3
Trigger Term Quality	It includes 'Clean Code' and 'Robert C. Martin' which are recognizable terms a user might mention, but lacks natural trigger terms like 'refactor', 'readability', 'naming conventions', 'code smell', 'simplify', or 'maintainability' that users would commonly say.	2 / 3
Distinctiveness Conflict Risk	The reference to 'Clean Code' by Robert C. Martin provides some distinctiveness, but 'transform code' is broad enough to overlap with general code review, refactoring, or linting skills.	2 / 3
	Total	7 / 12 Passed

Validation

90%

Warnings & errors only

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

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/clean-code/SKILL.md
Commit: 7520423

Reviewed: ~15 hours ago

Table of Contents

Discovery Implementation Validation

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.