clean-comments
Remove unnecessary, redundant, or obvious code comments while preserving valuable explanations. Use when cleaning up comments, removing verbose documentation, simplifying inline comments, or preparing code for review.
Best use case
clean-comments is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Remove unnecessary, redundant, or obvious code comments while preserving valuable explanations. Use when cleaning up comments, removing verbose documentation, simplifying inline comments, or preparing code for review.
Teams using clean-comments should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/clean-comments/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How clean-comments Compares
| Feature / Agent | clean-comments | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Remove unnecessary, redundant, or obvious code comments while preserving valuable explanations. Use when cleaning up comments, removing verbose documentation, simplifying inline comments, or preparing code for review.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Comment Cleanup
This guide is for removing unnecessary, redundant, or obvious code comments while preserving valuable explanations. Use this when cleaning up verbose documentation or preparing code for review.
## Core Principles
1. **Remove obvious comments**: Delete comments that merely restate what the code clearly does (e.g., '// increment counter' above 'counter++')
2. **Keep complexity explanations**: Preserve comments at decision points, complex algorithms, or non-obvious implementations
3. **Brevity for members**: Keep class and function documentation concise - one line when possible, focusing on the 'why' not the 'what'
4. **Deprecation selectivity**: Remove deprecated/outdated code comments unless they provide critical migration context
5. **Trust readable code**: If function names and parameters clearly convey purpose, additional explanation is redundant
## Review Criteria
When reviewing code, ask yourself:
- Does this comment add value beyond what well-named code already communicates?
- Does it explain business logic, edge cases, or architectural decisions? → **Keep**
- Could this comment block be reduced to a single meaningful line? → **Simplify**
- Is this a TODO/FIXME comment referencing completed work? → **Remove**
- Would this help a new developer understand non-obvious behavior? → **Keep**
## Batch Processing
- Process **max 15 files per session** for manageable reviews
- Focus on clarity through code structure rather than excessive documentation
- Preserve only high-value comments that answer questions the code cannot
## Examples
### ❌ Remove (Obvious)
```python
# Increment the counter
counter += 1
# Check if user is None
if user is None:
return
# Loop through items
for item in items:
process(item)
```
### ✅ Keep (Valuable)
```python
# Use exponential backoff to avoid overwhelming the API
# Max retries: 3, delays: 1s, 2s, 4s
retry_with_backoff(api_call)
# IMPORTANT: Must validate before save to prevent orphaned records
# See issue #1234 for context
if not validator.check(data):
raise ValidationError
# Performance: O(n log n) - don't change to bubble sort
quicksort(data)
```
### 🔄 Simplify (Verbose → Concise)
```python
# Before:
# This function calculates the total price by iterating through
# all items in the cart, multiplying each item's quantity by its
# price, and then summing all the results together to get the final total.
def calculate_total(cart):
return sum(item.quantity * item.price for item in cart)
# After:
# Includes bulk discount calculation for quantities >10
def calculate_total(cart):
return sum(item.quantity * item.price for item in cart)
```
## Output
The output should be the cleaned code with only high-value comments remaining. Each preserved comment should answer questions that the code itself cannot.
**Remember**: The best comment is often no comment when the code speaks for itself.Related Skills
todo-manage
Manage and organize TODO.md at project root - plan features, track progress, mark tasks complete, and clean up completed items. Use when planning tasks, organizing work, reviewing priorities, or managing the project TODO list. Access via /dipeotodos command.
test-backend-router
Test implementation of thin router skill for DiPeO backend. Provides decision criteria and documentation anchors for FastAPI server, CLI (dipeo run/results/metrics/compile/export), SQLite schema, and MCP integration in apps/server/. Use when task mentions CLI commands, server endpoints, database queries, or MCP tools.
separate-monolithic-python
Break large Python files (>500 LOC) into smaller, well-organized modules with proper package structure. Use when a Python file is too large, monolithic, or needs refactoring. Triggered by requests mentioning "too large", "separate", "split", "break up", or "refactor" for Python files.
maintain-docs
Update and maintain documentation to reflect current implementation after code changes, refactoring, or new features. Remove temporal language, verify accuracy against code, and keep docs current. Use when updating docs, syncing documentation, removing outdated info, or after implementing features.
import-refactor
Update all import statements, module references, string paths, and config references after moving or renaming files and modules. Handles Python, TypeScript, and JavaScript imports. Use when moving files, renaming modules, restructuring directories, or consolidating code.
skill-generator
Create new Claude Code skills with proper structure and best practices. Use when the user wants to create a new skill, extend Claude's capabilities, or needs help structuring a SKILL.md file.
doc-lookup
Locate and retrieve specific documentation sections from DiPeO's docs/ by heading anchors or keywords. Returns minimal, targeted excerpts instead of full files. Use when you need precise documentation context without loading entire guides.
dipeo-package-maintainer
Router skill for DiPeO runtime Python code (execution handlers, service architecture, domain models, LLM infrastructure). Use when task mentions node handlers, EventBus, ServiceRegistry, Envelope pattern, or domain logic. For simple tasks, handle directly; for complex work, escalate to dipeo-package-maintainer agent.
dipeo-frontend-dev
Router skill for DiPeO frontend (React, visual editor, GraphQL integration, TypeScript types). Use when task mentions React components, diagram editor, GraphQL hooks, or type errors. For simple tasks, handle directly; for complex work, escalate to dipeo-frontend-dev agent.
dipeo-codegen-pipeline
Router skill for DiPeO code generation pipeline (TypeScript specs → IR → Python/GraphQL). Use when task mentions TypeScript models, IR builders, generated code diagnosis, or codegen workflow. For simple tasks, handle directly; for complex work, escalate to dipeo-codegen-pipeline agent.
dipeo-backend
Router skill for DiPeO backend ecosystem (server/ and cli/): FastAPI server, CLI tools, database, MCP integration. Use when task mentions CLI commands, server endpoints, database queries, or MCP tools. For simple tasks, handle directly; for complex work, escalate to dipeo-backend agent.
reply-fix-to-review-comments
GitHub PR のレビューコメント（インライン）に対し、直前の会話で対応した commit を紐付けて「<commit URL> で修正しました」という Reply をまとめて投稿する。「レビュー Reply して」「レビューコメントに返信して」「修正報告投稿して」などのリクエストで使用。コード修正そのものは扱わず、修正・commit 済みの状態から呼ぶ前提。