you-might-not-need-a-comment

Analyze and fix redundant or self-explanatory inline comments — remove noise, promote genuine documentation to TSDoc

Quality

75%

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/you-might-not-need-a-comment/SKILL.md

Quality

Content

83%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 an exemplary lean, example-driven instruction skill with clear detection rules and a strong bias section, and the never-touch list prevents over-deletion. Its weaknesses are the missing post-fix validation step for a batch destructive pass and a reference to a scripts/ directory that does not exist in this bundle.

Suggestions

Add a verification step after applying fixes, e.g. re-run the annotation-grep script (or lint/build) to confirm no load-bearing kebab-tag annotation or tooling directive was deleted.

Resolve the dangling reference: either include the scripts/ file that greps for the kebab-tag annotations or drop the mention of 'a script under scripts/'.

Expand the Steps section slightly to state how scope is determined (diff, PR, directory) before analysis begins.

Dimension	Reasoning	Score
Conciseness	Lean and efficient throughout: 'Code says what and how; a comment earns its place only by explaining why' plus terse, example-anchored pattern lists. Every token earns its place and nothing explains what Claude already knows.	5 / 5
Actionability	Instruction-only but fully actionable: paired examples ('// increment counter' above 'counter++'), an explicit never-touch list ('// biome-ignore', kebab-tag annotations), and concrete fix=true/false behavior cover the common cases. Code absence is not penalized for instruction-only skills with actionable guidance.	5 / 5
Workflow Clarity	The two-step sequence (analyze the scope; apply or propose fixes) is clear, but this is a batch destructive pass — deleting comments across a codebase — with no validation or verification step, which caps workflow clarity at 3.	3 / 5
Progressive Disclosure	A short single file with well-organized sections needs no external references, but the body cites 'a script under `scripts/`' and script-enforced annotations while the bundle contains no scripts/ directory — a dangling reference against the actual bundle structure.	4 / 5
	Total	17 / 20 Passed

Description

66%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 states concrete, third-person capabilities in a distinct niche, but omits any 'when to use' trigger guidance. Adding an explicit 'Use when…' clause with natural trigger phrases would raise completeness and trigger-term quality.

Suggestions

Append an explicit trigger clause, e.g. 'Use when asked to clean up, remove, or tidy comments, or when a diff adds redundant or self-explanatory comments.'

Include common user phrasings like 'commented-out code' or 'noise comments' to broaden natural keyword coverage.

Optionally name the detectable sub-cases (commented-out code, banner/section-divider comments) to make the capability coverage comprehensive.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions — 'Analyze and fix redundant or self-explanatory inline comments', 'remove noise', 'promote genuine documentation to TSDoc'. Not 5 because coverage has gaps: detectable sub-cases like commented-out code or banner comments are not surfaced.	4 / 5
Completeness	The 'what' is clear and specific, but there is no 'Use when…' clause or any equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	'redundant … inline comments', 'self-explanatory comments', 'TSDoc' are phrases a user would naturally say when asking for this. A few natural variants are missing ('clean up comments', 'commented-out code', 'delete comments'), so it sits between the good-coverage (4) and comprehensive (5) anchors.	4 / 5
Distinctiveness Conflict Risk	A clear niche (inline-comment hygiene, TSDoc promotion) with distinct triggers; only minor overlap risk with general code-cleanup or linting skills.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: simstudioai/sim
Path: .agents/skills/you-might-not-need-a-comment/SKILL.md
Commit: 8725250

Reviewed: 3 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.