Agent skill

comment-generator

Generate code comments and docstrings. Use when user asks to "add comments", "document this code", "explain with comments", or "add docstrings".

Stars 5
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/Dexploarer/claudius-skills/tree/main/examples/beginner/simple-skills/comment-generator

SKILL.md

Comment Generator Skill

Automatically generates clear, helpful comments for code.

When to Use

This skill activates when the user wants to add comments to their code:

  • "Add comments to this function"
  • "Document this code"
  • "Add docstrings to my Python class"
  • "Explain this with inline comments"

Instructions

Step 1: Identify Language

Determine the programming language from:

  • File extension
  • Syntax patterns
  • User specification

Step 2: Choose Comment Style

JavaScript/TypeScript:

javascript
/**
 * Calculates the sum of two numbers
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} The sum
 */
function add(a, b) {
  return a + b;
}

Python:

python
def add(a, b):
    """
    Calculates the sum of two numbers.

    Args:
        a (int): First number
        b (int): Second number

    Returns:
        int: The sum of a and b
    """
    return a + b

Java:

java
/**
 * Calculates the sum of two numbers
 * @param a First number
 * @param b Second number
 * @return The sum
 */
public int add(int a, int b) {
    return a + b;
}

Step 3: Comment Structure

For functions/methods:

  1. Summary: What it does (one line)
  2. Parameters: Each parameter explained
  3. Returns: What it returns
  4. Throws/Raises: Any exceptions (if applicable)
  5. Examples: Usage example (if complex)

For classes:

  1. Summary: What the class represents
  2. Attributes: Key properties
  3. Usage: How to instantiate and use

For complex logic:

  1. Inline comments: Explain why, not what
  2. Section comments: Mark major sections
  3. TODO/FIXME: Note improvements needed

Step 4: Write Clear Comments

Good comments:

  • Explain WHY, not just WHAT
  • Use clear, simple language
  • Are concise but complete
  • Add value (don't state the obvious)

Bad comments:

javascript
// Add a and b
function add(a, b) {
  return a + b;  // Return the sum
}

Better:

javascript
/**
 * Combines two monetary values, useful for calculating totals
 * Handles floating point precision for currency
 */
function add(a, b) {
  return Math.round((a + b) * 100) / 100;  // Round to 2 decimals
}

Examples

Example 1: Simple Function

Input:

javascript
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

Output:

javascript
/**
 * Calculates the total price of all items in a collection
 * @param {Array<{price: number}>} items - Array of items with price property
 * @returns {number} Total price of all items
 * @example
 * const total = calculateTotal([{price: 10}, {price: 20}]); // Returns 30
 */
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

Example 2: Complex Function

Input:

python
def process_data(data, filters=None):
    if not filters:
        filters = []
    result = []
    for item in data:
        valid = True
        for f in filters:
            if not f(item):
                valid = False
                break
        if valid:
            result.append(item)
    return result

Output:

python
def process_data(data, filters=None):
    """
    Filters a dataset using multiple filter functions.

    Applies each filter function to every item in the dataset.
    Only items that pass all filters are included in the result.

    Args:
        data (list): Collection of items to filter
        filters (list of callable, optional): Filter functions that return True/False.
                                             Defaults to empty list (no filtering).

    Returns:
        list: Filtered dataset containing only items that passed all filters

    Example:
        >>> data = [1, 2, 3, 4, 5]
        >>> is_even = lambda x: x % 2 == 0
        >>> is_positive = lambda x: x > 0
        >>> process_data(data, [is_even, is_positive])
        [2, 4]
    """
    if not filters:
        filters = []

    result = []

    for item in data:
        valid = True

        # Apply each filter - item must pass all filters
        for f in filters:
            if not f(item):
                valid = False
                break  # Skip remaining filters if one fails

        if valid:
            result.append(item)

    return result

Tips

For Beginners

  • Start with function/method summaries
  • Add parameter descriptions
  • Include simple examples

For Intermediate

  • Add type information
  • Document exceptions
  • Include edge cases

For Advanced

  • Add algorithmic complexity
  • Document thread safety
  • Include performance notes

What NOT to Comment

❌ Don't comment obvious code:

javascript
// Increment i
i++;

❌ Don't duplicate code in comments:

javascript
// Set name to "John"
name = "John";

❌ Don't leave outdated comments:

javascript
// TODO: Fix this next week
// (Written 2 years ago)

Remember

  • Comments should add value
  • Update comments when code changes
  • Explain complex logic
  • Document public APIs thoroughly
  • Keep private code comments minimal but helpful

Expand your agent's capabilities with these related and highly-rated skills.

Dexploarer/claudius-skills

smart-contract-generator

Generates Solidity smart contracts with security best practices (ERC-20, ERC-721, ERC-1155, custom). Use when user asks to "create smart contract", "solidity contract", "erc20 token", "nft contract", or "web3 contract".

5 2
Explore
Dexploarer/claudius-skills

threejs-scene-builder

Comprehensive Three.js and React Three Fiber skill for creating 3D scenes, characters, NPCs, procedural generation, animation retargeting, and interactive experiences. Use when user asks to "create Three.js scene", "setup React Three Fiber", "add 3D character", "create NPC AI", "procedural 3D generation", "retarget animation", "setup avatar system", or "create 3D game".

5 2
Explore
Dexploarer/claudius-skills

wcag-compliance-checker

Checks websites for WCAG 2.1 Level AA compliance, identifies accessibility violations, and provides remediation guidance. Use when user asks to "check accessibility", "wcag compliance", "a11y audit", "accessibility violations", or "screen reader testing".

5 2
Explore
Dexploarer/claudius-skills

kubernetes-manifest-generator

Generates Kubernetes manifests (Deployments, Services, Ingress, ConfigMaps, Secrets) with best practices for production workloads. Use when user asks to "create k8s manifest", "generate Kubernetes deployment", "setup k8s service", or "create Kubernetes resources".

5 2
Explore
Dexploarer/claudius-skills

terraform-module-builder

Generates reusable Terraform modules with best practices for AWS, Azure, GCP infrastructure as code. Use when user asks to "create Terraform module", "generate IaC module", "setup Terraform", or "create infrastructure module".

5 2
Explore
Dexploarer/claudius-skills

translation-key-extractor

Extracts hardcoded strings from code and converts them to translation keys for i18n. Use when user asks to "extract translations", "find hardcoded strings", "internationalize code", "setup i18n", or "create translation files".

5 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results