code-comment-generator

Generates meaningful comments and documentation for code to improve maintenance and readability. Use when adding documentation to Python or Java code, including function/method docstrings, class documentation, inline explanations for complex logic, and code annotations (TODO, FIXME). Analyzes existing comment style in the codebase to match conventions. Produces clear, concise comments that explain the "why" not just the "what", following best practices for each language.

1.23x

Quality

78%

Does it follow best practices?

Impact

89%

1.23x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/code-comment-generator/SKILL.md

Quality

Content

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

Highly actionable with complete, executable examples and a clear multi-step workflow, but materially hurt by verbosity and over-inlining. Much of the redundant Python/Java example pairs and basic comment-quality guidance could move into the existing reference files.

Suggestions

Move the large before/after code example sets and the 'Comment Quality Guidelines' basics into references/comment_examples.md, keeping only one representative example per concept in SKILL.md to cut the body roughly in half.

Consolidate the Language-Specific Guidelines (Python/Java docstring and Javadoc formats) into references/style_guides.md and link out from SKILL.md instead of inlining both languages.

Avoid re-teaching concepts Claude already knows (e.g., 'don't state the obvious', 'keep comments up-to-date'); keep only the skill-specific conventions and the analyze-existing-style step that are non-obvious.

Dimension	Reasoning	Score
Conciseness	At ~660 lines the body is noticeably verbose: nearly every pattern is repeated verbatim in both Python and Java, and it explains basics Claude already knows ('Don't state the obvious', 'explain WHY not WHAT', what a docstring/Javadoc is), adding substantial padding beyond 'some' unnecessary explanation.	2 / 5
Actionability	Provides fully executable, copy-paste-ready Python and Java examples covering docstrings, Javadoc, inline comments, class/module documentation, and annotations (TODO/FIXME/HACK/OPTIMIZE), with the common cases concretely covered.	5 / 5
Workflow Clarity	A clear 6-step sequence (analyze style → understand code → write docs → add inline → document classes → add annotations) with sub-bullets; it is non-destructive so the validation cap does not apply, but explicit verification checkpoints are absent, leaving it just below the top anchor.	4 / 5
Progressive Disclosure	Real references (comment_examples.md, style_guides.md) are clearly signaled in a Resources section, but large blocks of example and language-specific guideline content that belong in those reference files are inlined in SKILL.md, so structure is only partially appropriate.	3 / 5
	Total	14 / 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, well-scoped description that explicitly states both capabilities and a 'Use when' trigger with concrete, natural terms. It is comprehensive and distinct; only minor synonym/extension coverage keeps trigger quality from the top anchor.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'function/method docstrings, class documentation, inline explanations for complex logic, and code annotations (TODO, FIXME)', plus 'Analyzes existing comment style in the codebase to match conventions' — giving comprehensive coverage of the skill's capabilities.	5 / 5
Completeness	Explicitly answers both 'what' ('Generates meaningful comments and documentation for code…') and 'when' ('Use when adding documentation to Python or Java code, including…') with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Includes natural terms users would say ('documentation', 'comments', 'docstrings', 'TODO', 'FIXME', 'Python or Java') but is missing common synonyms like 'Javadoc' and file extensions like '.py'/'.java', so it falls just short of the comprehensive anchor.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (code-comment generation scoped to Python/Java with named artifact types like docstrings and TODO/FIXME) with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

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

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (664 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: ArabelaTso/Skills-4-SE
Path: skills/code-comment-generator/SKILL.md
Commit: 4f38503

Reviewed: 8 days ago

Table of Contents

Discovery Implementation Validation

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.