CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

documenting-rust-code

Rust documentation practices for HASH codebase. Use when writing doc comments, documenting functions/types/traits/modules, creating error sections, using intra-doc links, or following rustdoc conventions.

72

Quality

91%

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

86%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-structured conventions skill: concrete DO/DON'T rules, executable templates for each documentation pattern, a verification command, and clean progressive disclosure into four real reference files. The only refinements worth making are trimming mild redundancy and adding verification failure-handling guidance.

Suggestions

Add a short error-recovery note under Verification (e.g., fix broken intra-doc links and missing # Errors sections reported by cargo doc warnings, then re-run) to close the workflow feedback loop.

Remove or repurpose the introductory sentence under the H1, which repeats the frontmatter description, and merge the Quick Reference examples into Documentation Patterns to eliminate overlap.

DimensionReasoningScore

Conciseness

The body is lean and rule-based with terse DO/DON'T lists and compact code templates, explaining nothing Claude already knows. It falls short of 5 because the opening line 'Comprehensive guidance on documenting Rust code in the HASH repository following rustdoc conventions' duplicates the description, and the Quick Reference examples partially overlap the Documentation Patterns section.

4 / 5

Actionability

Every pattern ships a copy-paste-ready rustdoc template (basic doc comment, intra-doc links, inline vs. # Arguments styles, # Errors, module docs, hidden-line examples), plus the executable verification command 'cargo doc --no-deps --all-features'. This matches the 'fully executable, covers common cases' anchor.

5 / 5

Workflow Clarity

The flow is coherent — principles, patterns by complexity, then a Verification step — giving an explicit checkpoint. It is not 5 because there is no error-recovery loop for verification failures (e.g., what to do about broken intra-doc links or warnings from cargo doc), only the bare command.

4 / 5

Progressive Disclosure

SKILL.md stays an overview and delegates depth to four one-level-deep references, each a real file (function-, type-, error-documentation, examples-and-links) linked with a descriptive label. Content is appropriately split — the 200-300-line detail guides live in references, matching the 'clear overview with well-signaled references' anchor.

5 / 5

Total

18

/

20

Passed

Description

92%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 that names the domain, scopes it to the HASH codebase, and provides an explicit, concrete 'Use when' trigger list covering all major rustdoc activities. Its only weakness is modest trigger synonym coverage (no '///', 'cargo doc', or 'API docs' phrasing).

DimensionReasoningScore

Specificity

The description enumerates concrete actions — 'writing doc comments, documenting functions/types/traits/modules, creating error sections, using intra-doc links, or following rustdoc conventions' — giving comprehensive coverage of the domain. It fits the 5 anchor rather than 4 because no meaningful capability area of rustdoc practice is missing.

5 / 5

Completeness

It explicitly answers both what ('Rust documentation practices for HASH codebase') and when ('Use when writing doc comments, documenting functions/types/traits/modules, creating error sections, using intra-doc links, or following rustdoc conventions') with concrete trigger phrases. Not 4, because the 'when' clause is fully explicit and specific rather than something that could be sharpened.

5 / 5

Trigger Term Quality

Natural phrases a Rust user would say are present ('doc comments', 'rustdoc', 'intra-doc links', 'error sections'), but common variations like '///', '//!', 'cargo doc', or 'API docs' are absent. Good coverage with a few natural terms missing matches the 4 anchor rather than 5's synonym-and-extension-level completeness.

4 / 5

Distinctiveness Conflict Risk

The Rust/rustdoc niche ('doc comments', 'intra-doc links', 'error sections') is distinct from general coding or documentation skills, so conflict risk is minimal. It clearly matches the 'clear niche with distinct triggers' anchor.

5 / 5

Total

19

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

hashintel/hash

Path

.agents/skills/documenting-rust-code/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.