CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

code-documentation

Guide for writing effective code documentation, including docstrings, JSDoc, dartdoc, and implementation comments. Use this skill when writing new code, adding features, or improving existing documentation in Dart, Python, or TypeScript to ensure clarity and maintainability.

Quality

84%

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

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.

A well-structured, lean instruction skill: concrete style rules with good/bad pairs, a clear documentation structure sequence, a verification checklist, and correctly deferred language-specific detail in existing one-level references. The main improvement opportunities are trimming the redundant opening line and adding one inline before/after docstring example.

Suggestions

Trim the redundant opening sentence "This skill provides comprehensive guidelines for documenting code..." since it restates the frontmatter description and the section headings already convey the scope.

Add one short inline before/after docstring example (e.g., a Dart or Python public member) in the Writing Guidelines section so the style rules are demonstrated end-to-end without opening a reference file.

DimensionReasoningScore

Conciseness

The body is efficient with concrete good/bad pairs and no padding, but the opening line "This skill provides comprehensive guidelines..." partially restates the description and a few soft hedges ("Strongly consider adding code samples") could be tightened, fitting anchor 4 rather than the every-token-earns-its-place anchor 5.

4 / 5

Actionability

Gives concrete, executable guidance such as the rewrite pairs ("This method is used to calculate the total." -> "Calculates the total.") and "Whether this widget is enabled.", plus a 4-step documentation structure. For an instruction-only skill this is mostly actionable, but no inline docstring example shows the guidance applied end-to-end, keeping it below anchor 5.

4 / 5

Workflow Clarity

The "General Structure" section sequences the documentation pattern (summary, blank line, details, annotations) and the "Review Checklist" provides explicit verification checkpoints, matching anchor 4. It is not 5 because the checklist has no error-recovery feedback loop, and not 3 because checkpoints are explicit rather than implicit.

4 / 5

Progressive Disclosure

The body is a clear overview with well-signaled, one-level-deep references (references/dart.md, references/typescript.md, references/python.md — all verified to exist), and language-specific detail is appropriately split into those files, exactly matching the anchor-5 example pattern.

5 / 5

Total

17

/

20

Passed

Description

83%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 with a clear what-and-when structure, explicit trigger activities, third-person voice, and named languages and documentation formats. Minor gaps are the thin action list beyond "Guide for writing" and a few missing natural synonyms such as "code comments" or "documenting code".

DimensionReasoningScore

Specificity

Names the domain and several concrete documentation artifacts ("docstrings, JSDoc, dartdoc, and implementation comments"), but the only action is "Guide for writing" with no broader action coverage, so it falls short of the comprehensive anchor 5 yet exceeds the 1-2 concrete actions of anchor 3.

4 / 5

Completeness

Clearly answers both: "what" ("Guide for writing effective code documentation, including docstrings, JSDoc, dartdoc, and implementation comments") and "when" ("Use this skill when writing new code, adding features, or improving existing documentation in Dart, Python, or TypeScript") with concrete trigger phrases, matching the anchor-5 example pattern.

5 / 5

Trigger Term Quality

Includes natural phrases users would say ("writing new code", "adding features", "improving existing documentation", "docstrings") plus language names Dart, Python, and TypeScript, but misses common synonyms like "code comments", "API docs", or "documenting code".

4 / 5

Distinctiveness Conflict Risk

The documentation focus and named languages make it mostly distinct, but the trigger "writing new code, adding features" is broad enough to overlap with general coding skills, fitting anchor 4 rather than the minimal-conflict anchor 5.

4 / 5

Total

17

/

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

flutter/agent-plugins

Path

.agents/agents/reidbaker-agent/skills/code-documentation/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.