clean-code

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

Quality

50%

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 ./.agents/skills/clean-code/SKILL.md

Quality

Content

60%Weight 40%Scale 1-5

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

The body is a well-structured, actionable standards reference with concrete rules and a solid verification workflow, but it is padded with explanations of concepts Claude already knows and a redundant summary, and the verification-script mapping is arguably scope creep.

Suggestions

Remove or compress explanations of well-known principles (SRP/DRY/KISS/YAGNI/Boy Scout) — keep the names and the rules Claude would not infer, drop the glossary-style definitions.

Delete the redundant Summary table, which restates the anti-patterns and Do/Don't already covered, and reduce repeated 🔴/MANDATORY/CRITICAL emphasis to a single callout per section.

Move the large agent→script verification mapping into a separate reference file and link to it from SKILL.md to tighten the core standards document.

Dimension	Reasoning	Score
Conciseness	It explains basic concepts Claude already knows (SRP/DRY/KISS/YAGNI/Boy Scout), repeats the rules in a redundant Summary table, and leans heavily on repeated 🔴/MANDATORY/CRITICAL emphasis, constituting several padded sections (anchor 2); not 3 because the concept explanations and duplicate summary are clear violations, not 1 because it is table-based rather than severely verbose prose.	2 / 5
Actionability	Concrete rules with specific thresholds ('Max 20 lines, ideally 5-10', 'Max 3 arguments', 'SCREAMING_SNAKE: MAX_RETRY_COUNT') and copy-paste verification commands give mostly executable guidance (anchor 4); not 5 because there are no worked before/after code examples, not 3 because the guidance is concrete rather than pseudocode.	4 / 5
Workflow Clarity	The script-output handling is a clear 5-step sequence with a re-run feedback loop, and before-edit/self-check checklists provide checkpoints (anchor 4); validation is present so the destructive-cap does not apply; not 5 because the main editing flow is a 'think first' prompt rather than a hard gate, not 3 because checkpoints are explicit.	4 / 5
Progressive Disclosure	A single well-sectioned file with clear headers and no nested references (anchor 4); no bundle files exist to navigate; not 5 because the large agent→script mapping table could arguably live in a separate reference, not 3 because structure is good and clearly signaled rather than merely 'some'.	4 / 5
	Total	14 / 20 Passed

Description

41%Weight 40%Scale 1-5

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 conveys a clear domain and style intent but reads as a qualities list rather than a capability/trigger statement, lacks a 'Use when...' clause, and is too broad to distinguish from other coding skills.

Suggestions

Rewrite as concrete actions, e.g. 'Enforces concise, direct coding standards: small functions, clear naming, guard clauses, no over-engineering or redundant comments.'

Add an explicit trigger clause: 'Use when writing or refactoring any code, applying coding standards, or reviewing code quality.'

Narrow scope or add distinctive triggers (e.g. 'refactor', 'clean code', 'reduce complexity') to lower conflict risk with other coding skills.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Pragmatic coding standards') but only lists style qualities ('concise, direct, no over-engineering, no unnecessary comments') rather than concrete actions, matching anchor 2; it is not 3 because no concrete actions are enumerated and not 1 because the domain is explicitly named.	2 / 5
Completeness	A clear 'what' is present (pragmatic coding standards with style directives) but the description field has no 'Use when...' trigger clause, so per the guideline completeness is capped at 3; not 2 because the 'what' is reasonably clear, not 4 because 'when' is entirely absent from the description.	3 / 5
Trigger Term Quality	It carries a few relevant keywords ('coding standards', 'over-engineering', 'comments') but misses the natural phrases users actually say ('clean code', 'refactor', 'code review'), fitting anchor 3; not 2 because a natural keyword is present, not 4 because common synonyms are absent.	3 / 5
Distinctiveness Conflict Risk	Scoped to code but stated to apply to ALL code writing, so it overlaps heavily with many coding skills (anchor 2); not 1 because it is not entirely generic beyond code, not 3 because it is not 'somewhat specific' — it is maximally broad within coding.	2 / 5
	Total	10 / 20 Passed

Validation

87%

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 — 14 / 16 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	14 / 16 Passed

Repository: vudovn/ag-kit
Path: .agents/skills/clean-code/SKILL.md
Commit: 211561c

Reviewed: 12 days 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.