CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

doc-comments

Update doc comments

54

Quality

68%

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 ./.github/skills/doc-comments/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

78%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 content is a strong example of a lean, instruction-only skill: every guideline is a specific, checkable rule, cleanup mode is crisply delimited, and there is zero padding. The only real improvements are minor — a before/after doc-comment example and a post-edit verification step — plus trimming the persona framing.

DimensionReasoningScore

Conciseness

The body is lean and rule-dense with no explanations of concepts Claude already knows; every guideline is a compact, checkable rule. It sits at 4 rather than 5 only because the "# Role" persona framing ("You are an expert technical documentation editor...") is minor over-explanation that could be trimmed.

4 / 5

Actionability

The guidelines are unusually concrete and executable for an instruction-only skill — specific examples like "{@link Uri address}" label preservation, `code` formatting with `undefined`, the 120-character limit, and forbidden product terms. It falls short of 5 due to minor gaps: "in appropriate locations" is vague and no before/after example of a well-formed doc comment is provided.

4 / 5

Workflow Clarity

This is a simple single-task skill under 50 lines with a clear pre-checkpoint ("Fetch and review relevant code context ... before making changes") and a well-defined conditional branch (Cleanup Mode with its strict limit). It stays at 4 rather than 5 because "update code documentation comments in appropriate locations" leaves mild ambiguity and there is no final verification step such as confirming public API signatures are untouched.

4 / 5

Progressive Disclosure

The skill is self-contained, under 50 lines, has no bundle files, and needs no external references; the body is cleanly sectioned (Role, Instructions, Guidelines, Cleanup Mode) with the special mode clearly separated. Per the rubric's simple-skill guideline, this earns a 5 on well-organized sections alone.

5 / 5

Total

17

/

20

Passed

Description

45%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 is concise but under-specified: it names the domain and a single generic action with no trigger guidance, no capability detail, and no synonyms. Since the skill sets disable-model-invocation: true the description is not used for auto-triggering, but as written it still reads as a minimal three-word label that would benefit from a 'Use when...' clause and broader keyword coverage.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user asks to update, clean up, or fix JSDoc, docstring, or API documentation comments in code."

Enumerate 1-2 concrete capabilities to raise specificity, e.g. "Update doc comments: fix grammar and spelling, add {@link} references, and apply house style rules to JSDoc/docstring comments."

Include natural synonyms and variations users would say — "documentation comments", "JSDoc", "docstrings", "API docs" — to improve trigger-term coverage and distinctiveness.

DimensionReasoningScore

Specificity

"Update doc comments" names the domain ("doc comments") but offers only a single generic action ("Update"), matching the anchor-2 pattern 'Processes PDF files'. It does not reach 3 because that anchor requires 1-2 concrete actions (e.g., 'fixes grammar and adds {@link} references'), and only one vague action is present.

2 / 5

Completeness

The 'what' is explicitly stated ("Update doc comments") but the 'when' is entirely absent, and the judging guidelines cap completeness at 3 for a missing 'Use when...' clause. It stays at 3 rather than dropping to 2 because the 'what' is stated clearly, not vague.

3 / 5

Trigger Term Quality

"doc comments" is a natural, relevant phrase users would actually say, but it is the only keyword; common variations like "documentation", "JSDoc", "docstrings", or "API docs" are missing. This matches anchor 3 ('some relevant keywords but missing common variations or synonyms') and falls short of 4, whose example shows multiple keyword groups.

3 / 5

Distinctiveness Conflict Risk

"doc comments" is a fairly narrow artifact type, but the bare three-word description provides no scope qualifiers and could plausibly trigger for general documentation-writing or code-editing requests, matching anchor 3 ('somewhat specific but could still overlap with similar skills'). It does not fit 4, which expects clearer differentiation akin to 'Works with PDF and Word document files'.

3 / 5

Total

11

/

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

description_field

'description' is very short (19 chars), consider making it more detailed

Warning

Total

15

/

16

Passed

Repository

microsoft/vscode

Path

.github/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.