clean-code

Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments

Quality

31%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agent/skills/clean-code/SKILL.md

Quality

Content

62%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill effectively communicates clean code principles through well-structured tables and includes strong workflow validation sections. However, it conflates two distinct concerns: coding standards and agent orchestration/verification workflows. The verification scripts section significantly bloats what should be a focused coding standards skill, and the lack of concrete before/after code examples reduces actionability.

Suggestions

Extract the 'Verification Scripts' and 'Script Output Handling' sections into a separate orchestration or workflow skill - they don't belong in a clean code standards document

Add 2-3 concrete before/after code examples demonstrating key principles (e.g., show a 'bad' nested function refactored with guard clauses)

Remove redundant emphasis markers (multiple 🔴 CRITICAL/MANDATORY sections) - the rules should speak for themselves

Dimension	Reasoning	Score
Conciseness	The skill uses efficient table formats and avoids explaining basic concepts, but includes significant redundancy (multiple 'CRITICAL' and 'MANDATORY' sections) and the verification scripts section is overly detailed for a 'clean code' skill - it belongs in a separate orchestration/workflow skill.	2 / 3
Actionability	Provides clear rules and anti-patterns in table format, but lacks executable code examples demonstrating the principles. The 'Quick Check' example is pseudocode-like rather than actionable, and the verification scripts section lists commands but doesn't show how to apply clean code principles in practice.	2 / 3
Workflow Clarity	Clear sequencing for the 'Before Editing' and 'Self-Check' workflows with explicit validation checkpoints. The script output handling section provides a clear feedback loop (READ → SUMMARIZE → ASK → fix → re-run).	3 / 3
Progressive Disclosure	Content is organized into logical sections with tables, but everything is in one monolithic file. The verification scripts section (agent-specific tooling) should be in a separate file, and the skill mixes coding standards with orchestration concerns.	2 / 3
	Total	9 / 12 Passed

Description

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description fails on all dimensions by describing abstract principles rather than concrete capabilities. It reads more like a philosophy statement than a skill description, providing no actionable guidance for when Claude should select this skill over others. Without specific actions, trigger terms, or explicit usage conditions, this skill would be nearly impossible to correctly match to user requests.

Suggestions

Add specific concrete actions this skill enables (e.g., 'Writes clean, minimal code. Reviews code for unnecessary complexity. Removes redundant comments and abstractions.')

Include a 'Use when...' clause with natural trigger terms (e.g., 'Use when user asks for code review, refactoring, simplifying code, or mentions clean code, minimal code, or YAGNI principles.')

Narrow the scope to a specific context to reduce conflict risk (e.g., specify if this applies to code generation, code review, refactoring, or a particular language/framework).

Dimension	Reasoning	Score
Specificity	The description uses vague, abstract language like 'pragmatic coding standards' and 'no over-engineering' without listing any concrete actions Claude would perform. It describes qualities/principles rather than specific capabilities.	1 / 3
Completeness	Missing both 'what' (specific actions) and 'when' (explicit triggers). There is no 'Use when...' clause or equivalent guidance for when Claude should select this skill.	1 / 3
Trigger Term Quality	Contains no natural keywords users would say when requesting help. Terms like 'pragmatic' and 'over-engineering' are abstract concepts, not trigger phrases like 'write code', 'refactor', or 'code review'.	1 / 3
Distinctiveness Conflict Risk	Extremely generic - 'coding standards' could apply to virtually any programming task. Would conflict with any code-related skill since it doesn't specify a clear niche or distinct use case.	1 / 3
	Total	4 / 12 Passed

Validation

81%

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 — 9 / 11 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	9 / 11 Passed

Repository: lchenrique/politron-ide
Commit: 7114206

Reviewed: 4 months 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.