jsdoc-comment-generator
Jsdoc Comment Generator - Auto-activating skill for Technical Documentation. Triggers on: jsdoc comment generator, jsdoc comment generator Part of the Technical Documentation skill category.
35
3%
Does it follow best practices?
Impact
93%
1.00xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./planned-skills/generated/17-technical-docs/jsdoc-comment-generator/SKILL.mdQuality
Discovery
7%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 description is essentially a placeholder that repeats the skill name and category without providing any substantive information about what the skill does or when it should be used. It lacks concrete actions, meaningful trigger terms, and explicit usage guidance, making it nearly useless for skill selection among multiple options.
Suggestions
Add specific concrete actions such as 'Generates JSDoc comment blocks for JavaScript/TypeScript functions, classes, and modules, including @param, @returns, @throws, and @typedef annotations'.
Add an explicit 'Use when...' clause with natural trigger terms like 'Use when the user asks to document JavaScript code, add JSDoc comments, generate function documentation, or annotate types for JS/TS files'.
Remove the duplicated trigger term 'jsdoc comment generator' and replace with varied natural phrases users would actually say, such as 'document this function', 'add comments', 'JSDoc', 'JS documentation'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description only names the skill ('Jsdoc Comment Generator') and its category ('Technical Documentation') but does not describe any concrete actions like 'generates JSDoc comments for JavaScript functions' or 'adds @param, @returns, @throws annotations'. | 1 / 3 |
Completeness | The description fails to answer both 'what does this do' (no concrete actions described) and 'when should Claude use it' (no explicit 'Use when...' clause or meaningful trigger guidance beyond repeating the skill name). | 1 / 3 |
Trigger Term Quality | The only trigger terms listed are 'jsdoc comment generator' repeated twice. It misses natural user phrases like 'document this function', 'add JSDoc', 'JavaScript documentation', '@param', 'type annotations', or 'comment my code'. | 1 / 3 |
Distinctiveness Conflict Risk | The mention of 'JSDoc' provides some specificity that distinguishes it from generic documentation skills, but the lack of concrete actions and the broad 'Technical Documentation' category label could cause overlap with other documentation-related skills. | 2 / 3 |
Total | 5 / 12 Passed |
Implementation
0%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is an empty template with no actual content about JSDoc comment generation. It contains only boilerplate section headers and generic descriptions that repeat the skill name without providing any actionable guidance, code examples, or JSDoc-specific information. It would be entirely useless to Claude in performing JSDoc comment generation tasks.
Suggestions
Add concrete, executable JSDoc examples showing common patterns (e.g., @param, @returns, @typedef, @example) with before/after code snippets for functions, classes, and modules.
Define a clear workflow: 1) Analyze the function signature and body, 2) Determine parameter types and return types, 3) Generate the JSDoc block with appropriate tags, 4) Validate completeness against the function's actual interface.
Remove all boilerplate sections ('When to Use', 'Example Triggers', 'Capabilities') and replace with actual JSDoc tag reference tables and generation rules.
Include specific examples of input (a JavaScript function) and expected output (the complete JSDoc comment block) to make the skill copy-paste actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is entirely filler and boilerplate. It explains nothing Claude doesn't already know and provides zero domain-specific information about JSDoc comment generation. Every section restates the skill name without adding value. | 1 / 3 |
Actionability | There is no concrete guidance whatsoever—no JSDoc syntax examples, no code snippets, no specific commands, no tag references. The skill describes rather than instructs, offering only vague promises like 'provides step-by-step guidance' without actually providing any. | 1 / 3 |
Workflow Clarity | No workflow, steps, or process is defined. The skill claims to provide 'step-by-step guidance' but contains zero actual steps. There are no validation checkpoints or any sequenced instructions. | 1 / 3 |
Progressive Disclosure | The content is a flat, repetitive document with no meaningful structure. There are no references to detailed files, no examples section, and no navigation to deeper content. The sections that exist are superficial and redundant. | 1 / 3 |
Total | 4 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
4dee593
- 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.