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".
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:
/**
* 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:
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:
/**
* 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:
- Summary: What it does (one line)
- Parameters: Each parameter explained
- Returns: What it returns
- Throws/Raises: Any exceptions (if applicable)
- Examples: Usage example (if complex)
For classes:
- Summary: What the class represents
- Attributes: Key properties
- Usage: How to instantiate and use
For complex logic:
- Inline comments: Explain why, not what
- Section comments: Mark major sections
- 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:
// Add a and b
function add(a, b) {
return a + b; // Return the sum
}
✅ Better:
/**
* 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:
function calculateTotal(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}
Output:
/**
* 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:
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:
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:
// Increment i
i++;
❌ Don't duplicate code in comments:
// Set name to "John"
name = "John";
❌ Don't leave outdated comments:
// 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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated 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".
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".
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".
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".
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".
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".
Didn't find tool you were looking for?