CtrlK
BlogDocsLog inGet started
Tessl Logo

doc-comments

Use this skill whenever writing or editing Rust `//`, `///`, or `//!` comments in Biome, including comments added incidentally and end-user rustdoc inside lint/assist declarations. For lint/assist rustdoc, also load lint-rule-development for content requirements. Do not use for formatter handling of comments in user code.

67

Quality

81%

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

SKILL.md
Quality
Evals
Security

Quality

Content

75%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.

A well-crafted instruction-only skill: it teaches a clear reader model, gives concrete BAD/GOOD patterns for every banned behavior, documents a codebase-specific convention with named exemplars, and closes with a real self-check loop. Its weaknesses are modest — a small amount of restated framing, a fragmentary positive example, and no intentional use of reference files despite a moderately long body.

Suggestions

Trim the Purpose section and the opening 'Scope boundary' note so the boundary is stated once, and shorten the Exemplar paragraph to the two or three facts that make the exemplar worth reading.

Replace the fragmentary `fn infer_types(...)` example with one complete positive `///` example (real signature and full doc comment) so the target register is shown, not just described.

Consider moving the Region Comments rules (naming, pairing, when-to-use) into a short reference file linked from a two-line summary, keeping SKILL.md as a leaner overview.

DimensionReasoningScore

Conciseness

Efficient: nearly every section carries codebase-specific rules (the deletion test, banned patterns with BAD/GOOD pairs, region-marker conventions, named crates) rather than concepts Claude already knows. Minor pads exist — the Purpose section restates the frontmatter's scope boundary, and the Exemplar paragraph runs long — which keeps it below the 'every token earns its place' level 5.

4 / 5

Actionability

Concrete and executable: BAD/GOOD rewrites for each banned pattern, exact region-marker syntax, named crates where the convention is established, a three-question self-check, and a named exemplar file. It falls short of 5 because the positive `///` example is a fragment (`fn infer_types(...)`) and there is no complete positive module-doc example inline.

4 / 5

Workflow Clarity

The body is sequenced (reader model → comment kinds → deletion test → banned patterns → conventions → editing rules) and ends with an explicit validation checkpoint with a fix-or-delete feedback loop ('re-read only the comments in your diff… Fix or delete what fails'). It is not a 5 because the bulk is reference material rather than an ordered procedure — the sequence lives in section ordering plus the final checklist. No destructive/batch cap applies.

4 / 5

Progressive Disclosure

Well-organized single-file structure with one-level-deep references only (the sibling lint-rule-development link and the external Diátaxis link), both clearly signaled in a References section; no bundle files exist to split content into. Above 4 would require either a genuinely small file or a deliberate split — at this length, sections like Region Comments or Behavior Documentation could arguably live in reference files, though nothing is buried or nested.

4 / 5

Total

16

/

20

Passed

Description

87%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 strong description: it names a precise niche, states explicit load/don't-load triggers, disambiguates against the one sibling skill that overlaps, and includes natural trigger terms. The only gap is that the actions described are generic verbs rather than an enumeration of the specific comment-writing sub-tasks the skill governs.

DimensionReasoningScore

Specificity

Names the domain and several concrete actions — writing/editing the three Rust comment kinds, covering incidentally-added comments, routing lint/assist rustdoc to a companion skill, and excluding formatter comment handling. The verbs themselves ('writing or editing') stay generic and the distinct sub-tasks the body covers (module docs, item docs, inline rationale) are not enumerated, so it falls short of the comprehensive level 5.

4 / 5

Completeness

Explicitly answers both questions: the 'what' is writing/editing the three comment kinds in Biome, and the 'when' is stated as a concrete trigger clause ('Use this skill whenever writing or editing Rust `//`, `///`, or `//!` comments in Biome'), reinforced by inclusion and exclusion cases. Anti-drift check against the level-4 anchor holds because the trigger is explicit, not merely implied.

5 / 5

Trigger Term Quality

Good natural-term coverage: 'Rust', 'comments', 'rustdoc', 'lint/assist', 'Biome', and all three comment sigils — phrases a contributor would actually say. Common synonyms such as 'doc comment(s)' and 'documentation' are absent, so it is not comprehensive enough for 5.

4 / 5

Distinctiveness Conflict Risk

A clear niche (developer-facing Rust comments in the Biome codebase) with explicit disambiguation against the one overlapping skill ('For lint/assist rustdoc, also load lint-rule-development') and an explicit exclusion ('Do not use for formatter handling of comments in user code'), leaving minimal conflict risk.

5 / 5

Total

18

/

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

relative_links

Relative link issues: 4 suspicious

Warning

Total

15

/

16

Passed

Repository
biomejs/biome
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.