CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

doc-comments

Use this skill whenever writing or editing Rust `//`, `///`, or `//!` comments in Biome, including contributor documentation and rustdoc exposed to users through configuration schemas, CLI help, workspace or daemon APIs, and lint or assist declarations. For lint or assist rustdoc, also load lint-rule-development. Do not use for formatter handling of comments in user code.

71

Quality

89%

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

88%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 policy skill: concrete and actionable throughout, with a coherent identify-audience → write → self-check workflow and a real validation checklist. The main improvement opportunities are trimming mild redundancy between style sections and splitting the detailed pattern catalogs into a reference file.

DimensionReasoningScore

Conciseness

The body is dense and prescriptive — nearly every sentence states a rule, a table row, or a BAD/GOOD contrast specific to Biome, with no padding about concepts Claude already knows. Minor trimming is possible (e.g., the ELI18 register explanation and the philosophy bullet list restate style guidance also covered in the end-user section), which keeps it at anchor 4 rather than the every-token-earns-its-place lean of anchor 5.

4 / 5

Actionability

For an instruction-only skill the guidance is highly concrete: a source-context-to-reader mapping table, per-surface content checklists, BAD/GOOD Rust comment examples for each banned pattern, the region-marker code block, and precise replacement rules ("Replace phrases such as \"returns `Some`\"... with the result the user observes"). Specific examples cover the common cases, matching anchor 5; the absence of executable code is expected and not penalized per the rubric's scoring notes.

5 / 5

Workflow Clarity

The editorial workflow is clearly sequenced: "Before editing a comment, trace where it is consumed" (audience identification first), then audience-specific writing guidance, banned patterns, and editing rules, ending with an explicit 6-item numbered "Self-Check Before Finishing" validation checklist. This matches anchor 5's clear sequence plus explicit validation checklist; anchor 4 would require missing checkpoints, and the self-check covers reader identification, self-containment, redundancy, and output inspection.

5 / 5

Progressive Disclosure

A single-file skill with well-organized sections and a clearly signaled References section listing one-level-deep external resources. It stays at anchor 4 rather than 5 because the ~250-line body inlines detailed catalogs (banned-pattern examples, region-comment conventions) that could sit in a reference file, and the in-body relative links (e.g., ../lint-rule-development/SKILL.md, ../../../crates/...) cannot be verified within this bundle, which has no reference files at all.

4 / 5

Total

18

/

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: concrete actions, an explicit trigger clause with routing and exclusion guidance, and natural terminology for its target audience of coding agents working on Biome. Minor room to add common synonyms like "doc comment" or "inline comment".

DimensionReasoningScore

Specificity

The description names the domain and concrete actions — "writing or editing Rust `//`, `///`, or `//!` comments" — and enumerates specific destinations ("configuration schemas, CLI help, workspace or daemon APIs, and lint or assist declarations") plus a negative trigger. It falls just short of anchor 5 because the core action set is essentially one activity (write/edit comments) rather than multiple distinct comprehensive actions.

4 / 5

Completeness

Both what and when are explicit: the what is "writing or editing Rust `//`, `///`, or `//!` comments in Biome... including contributor documentation and rustdoc exposed to users through configuration schemas, CLI help...", and the when is a concrete trigger clause "Use this skill whenever writing or editing Rust... comments in Biome" with routing ("For lint or assist rustdoc, also load lint-rule-development") and an exclusion ("Do not use for formatter handling of comments in user code"). This clearly matches anchor 5; anchor 4 would require the when to be less explicit or specific, which it is not.

5 / 5

Trigger Term Quality

Natural terms a Biome contributor would say are present: "Rust comments", "rustdoc", "contributor documentation", "CLI help", "lint or assist". A few natural synonyms are missing (e.g., "doc comment" spelled out, "inline comment", "module docs"), so it matches anchor 4 rather than the comprehensive synonym coverage of anchor 5.

4 / 5

Distinctiveness Conflict Risk

It occupies a clear niche — Rust comment/rustdoc audience policy for the Biome codebase — and explicitly disambiguates the closest conflict ("Do not use for formatter handling of comments in user code") and routes overlapping cases to another skill. Minimal conflict risk; matches anchor 5.

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: 5 suspicious

Warning

Total

15

/

16

Passed

Repository

biomejs/biome

Path

.agents/skills/doc-comments/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.