code-comment-generator
Generates code comments that explain non-obvious intent, constraints, and tradeoffs — not what the code already says. Use when code is correct but opaque, when documenting for future maintainers, or when a function's why is harder to see than its what.
Install with Tessl CLI
npx tessl i github:santosomar/general-secure-coding-agent-skills --skill code-comment-generator94
Quality
92%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Discovery
85%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong description that clearly articulates a specific capability (explaining intent/constraints/tradeoffs in comments) and provides explicit trigger conditions. The distinction between explaining 'why' vs 'what' creates a clear niche. Minor improvement could come from adding more natural trigger terms users might actually say.
Suggestions
Add common trigger variations like 'add comments', 'explain this code', 'annotate', or 'write documentation' to improve discoverability
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists specific concrete actions: 'Generates code comments that explain non-obvious intent, constraints, and tradeoffs' with clear differentiation from what it doesn't do ('not what the code already says'). | 3 / 3 |
Completeness | Clearly answers both what ('Generates code comments that explain non-obvious intent, constraints, and tradeoffs') and when ('Use when code is correct but opaque, when documenting for future maintainers, or when a function's why is harder to see than its what'). | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'code comments', 'documenting', 'maintainers', but misses common variations users might say like 'add comments', 'explain code', 'annotate', or 'documentation'. | 2 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with clear niche focus on 'why' over 'what', specifically targeting non-obvious intent and tradeoffs. Unlikely to conflict with general code documentation or explanation skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
100%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is an exemplary skill file that teaches a nuanced judgment task with exceptional clarity. It provides concrete decision criteria (the tables), a memorable heuristic (the rename test), a detailed worked example, and a clear output format—all without wasting tokens on concepts Claude already knows. The 'do not' section reinforces boundaries effectively.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section earns its place by teaching non-obvious judgment calls about commenting. No padding or explanation of concepts Claude already knows—it jumps straight into actionable criteria and examples. | 3 / 3 |
Actionability | Provides concrete, executable examples throughout—the 'rename test', the reconnect() worked example, and the output format template are all copy-paste ready and demonstrate exactly what good vs bad comments look like. | 3 / 3 |
Workflow Clarity | For a judgment-based skill (not a multi-step destructive operation), the workflow is crystal clear: evaluate against the tables, apply the rename test, use the output format. The single-task nature is handled with unambiguous guidance. | 3 / 3 |
Progressive Disclosure | Well-organized with clear sections (what deserves comments, what doesn't, the test, worked example, docstrings, do-nots, output format). At ~100 lines with no need for external references, the self-contained structure is appropriate. | 3 / 3 |
Total | 12 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- 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.