CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

you-might-not-need-a-comment

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

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

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
SKILL.md
Quality
Evals
Security

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.

An exceptionally lean and actionable body — concrete anti-pattern examples, an exact protected-tag list, and clear bias rules — undermined only by a Steps section that applies batch deletions with no validation feedback loop and references to scripts that are not part of the bundle.

Suggestions

Add a validation step after applying fixes (e.g. re-run `check:comment-hygiene` or verify lint/build still passes) to create a fix→verify→retry loop — the workflow currently ends at "apply the fixes" for a default-on batch deletion, capping workflow clarity at 3.

Ship the annotation-tag list (or a reference file enumerating it) inside the skill bundle: the body defers to "a script under `scripts/`" and `check:comment-hygiene`, but no such files exist here, leaving "any other `<kebab-tag>: <reason>` annotation" unverifiable.

Specify how to handle a scope argument that doesn't parse (e.g. fall back to current changes) so step 1 is unambiguous for every invocation.

DimensionReasoningScore

Conciseness

The body is lean and efficient with zero padding: no concept explanations, and every section ("The one rule that matters", "Anti-patterns to detect", "Patterns that ARE correct", "Bias", "Steps") carries decision-relevant content. Matches the anchor "Lean and efficient; assumes Claude's competence; every token earns its place" — nothing to trim, so not 4.

5 / 5

Actionability

Fully actionable for an instruction-only skill: concrete detection examples ("`// increment counter` above `counter++`"), an exact do-not-flag list naming specific tags (`// boundary-raw-fetch:`, `// biome-ignore`, `// rq-lint-allow:`), and explicit bias rules ("Prefer **deletion over rewriting**", "Never add new comments in this pass"). Per the rubric's code_vs_instruction note, absence of code is not penalized when guidance is this concrete.

5 / 5

Workflow Clarity

Steps are only "1. Analyze the specified scope... 2. If fix=true, apply the fixes" — a batch, destructive operation (deleting comments, fix defaults to true, scope can be "whole codebase") with no validation or verification step, so the guideline cap of 3 applies and takes precedence over the simple-skill exception. Not 4 because validation is entirely absent, not merely gappy.

3 / 5

Progressive Disclosure

Good structure for a 47-line single-file skill: well-organized sections, content appropriately inlined, no nested references. Not 5 because the body points to infrastructure absent from the bundle — "a script under `scripts/` greps for" and "`check:comment-hygiene` rejects both" reference scripts, but no `scripts/`, `references/`, or `assets/` directories exist, so the reader cannot verify which annotations are actually load-bearing.

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.

A specific, mostly distinct description with concrete actions, weakened by the complete absence of any "Use when..." trigger guidance and some missing natural synonyms. Adding an explicit trigger clause would lift completeness and trigger-term quality.

Suggestions

Add an explicit trigger clause, e.g. "Use when cleaning up code comments, removing unnecessary or noisy inline comments, or converting loose comment blocks to TSDoc" — the missing 'Use when' caps completeness at 3.

Include natural synonyms users would actually say: "unnecessary comments", "clean up comments", "comment noise".

Mention the propose-only mode (fix=false) to close the minor coverage gap in the action list.

DimensionReasoningScore

Specificity

"Analyze and fix redundant or self-explanatory inline comments — remove noise, promote genuine documentation to TSDoc" lists several concrete actions (analyze, fix, remove, promote), matching the anchor for several specific actions with minor gaps — it omits the propose-only (fix=false) mode. Not 5 because coverage is not comprehensive; not 3 because more than 1-2 concrete actions are explicitly named.

4 / 5

Completeness

The description has a clear "what" ("Analyze and fix redundant or self-explanatory inline comments — remove noise, promote genuine documentation to TSDoc") but no "Use when..." clause or equivalent trigger guidance, which per the judging guidelines caps completeness at 3. Not 4 because the "when" is entirely absent, not merely weakly implied.

3 / 5

Trigger Term Quality

Natural terms present: "redundant", "self-explanatory", "inline comments", "noise", "TSDoc" — good keyword coverage. Not 5 because common variations users would say ("unnecessary comments", "clean up comments") are missing; above 3 because coverage goes beyond a couple of generic keywords.

4 / 5

Distinctiveness Conflict Risk

Comment hygiene is a clear niche with distinct triggers ("redundant or self-explanatory inline comments", "promote ... to TSDoc"); mostly distinct with minor overlap risk against documentation-writing or linting skills. Not 5 because "promote genuine documentation to TSDoc" could also fire for a TSDoc-authoring request handled by a documentation skill.

4 / 5

Total

15

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

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

Reviewed

Table of Contents

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.