Fixes documentation issues including missing JSDoc, module-level comments, and @returns tags. Use when functions lack documentation or JSDoc is incomplete.
Adds JSDoc to undocumented functions, modules, and incomplete @returns tags. Triggers when exported functions lack JSDoc, files miss module-level comments, or existing JSDoc is missing @returns for non-obvious return values.
/plugin marketplace add mgd34msu/goodvibes-plugin/plugin install goodvibes@goodvibes-marketThis skill inherits all available tools. When active, it can use any tool Claude has access to.
scripts/check-docs.jsscripts/generate-jsdoc.jsFixes for code documentation issues. Good documentation explains intent, edge cases, and non-obvious behavior - not what the code obviously does.
P3 - Fix when convenient. Documentation improves maintainability but doesn't affect runtime.
Detection: Exported function without JSDoc comment.
Pattern: Public API without documentation.
// PROBLEM - no documentation
export function calculateDiscount(price: number, code: string): number {
// ...
}
Fix Strategy: Add focused JSDoc explaining what isn't obvious.
// SOLUTION - focused JSDoc
/**
* Applies a discount code to calculate the final price.
* @param price - Original price in cents
* @param code - Discount code (case-insensitive)
* @returns Final price after discount, minimum 0
* @throws {InvalidCodeError} When code is expired or invalid
*/
export function calculateDiscount(price: number, code: string): number {
// ...
}
What to document:
What NOT to document:
Pattern: File without top-level module documentation.
// PROBLEM - no module doc
import { db } from './database';
export function createUser() { ... }
Fix Strategy: Add @module JSDoc at file top.
// SOLUTION
/**
* @module validators/order
* @description Validation functions for order processing.
* Handles input sanitization and business rule enforcement.
*/
import { db } from './database';
export function createUser() { ... }
Module doc template:
/**
* @module {feature}/{filename}
* @description {One sentence describing the module's purpose}.
* {Optional second sentence about key functionality or usage context}.
*/
Pattern: JSDoc with @param but no @returns.
// PROBLEM - missing @returns
/**
* Calculates the total with tax.
* @param subtotal - Amount before tax
* @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
*/
function calculateTotal(subtotal: number, taxRate: number): number {
return subtotal * (1 + taxRate);
}
Fix Strategy: Add @returns when return value has non-obvious behavior.
// SOLUTION - add @returns
/**
* Calculates the total with tax.
* @param subtotal - Amount before tax in cents
* @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
* @returns Total amount in cents, rounded to nearest cent
*/
function calculateTotal(subtotal: number, taxRate: number): number {
return Math.round(subtotal * (1 + taxRate));
}
When @returns adds value:
node scripts/check-docs.js /path/to/src
node scripts/generate-jsdoc.js /path/to/file.ts
/**
* {Brief description of what the function does}.
* @param {paramName} - {Description including units/constraints}
* @returns {Description including units/edge cases}
* @throws {ErrorType} {When this error is thrown}
* @example
* const result = functionName(arg1, arg2);
*/
/**
* {Brief description of the class purpose}.
* @example
* const instance = new ClassName(config);
* instance.method();
*/
class ClassName {
/**
* Creates a new instance.
* @param config - Configuration options
*/
constructor(config: Config) {}
}
/**
* Configuration options for {feature}.
*/
interface Config {
/** Maximum number of retries (default: 3) */
maxRetries?: number;
/** Timeout in milliseconds (default: 5000) */
timeoutMs?: number;
/** Called when operation completes */
onComplete?: (result: Result) => void;
}
/**
* User identifier - either numeric ID or email string.
* Numeric IDs are for internal users, emails for external.
*/
type UserId = number | string;
/**
* Retries a failed operation with exponential backoff.
* @param operation - Async function to retry
* @param maxAttempts - Maximum retry count (default: 3)
* @returns Result of successful operation
* @throws Last error if all attempts fail
* @example
* const data = await withRetry(() => fetchData(id), 5);
*/
Why it's good:
/**
* This function retries an operation.
* @param operation - The operation to retry
* @param maxAttempts - The max attempts
* @returns The result
*/
Why it's bad:
// eslint.config.js
{
rules: {
'jsdoc/require-jsdoc': ['warn', {
require: {
FunctionDeclaration: true,
MethodDefinition: true,
ClassDeclaration: true,
},
contexts: [
'ExportNamedDeclaration > FunctionDeclaration',
'ExportNamedDeclaration > VariableDeclaration > VariableDeclarator > ArrowFunctionExpression',
],
}],
'jsdoc/require-param-description': 'warn',
'jsdoc/require-returns-description': 'warn',
},
}
eslint-plugin-jsdoc for validationThis skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.