playbooks

home / skills / openclaw / skills / comment-gen

comment-gen skill

/skills/lxgicstudios/comment-gen

This skill adds meaningful inline comments to complex Python code by explaining why decisions are made and how they affect behavior.

npx playbooks add skill openclaw/skills --skill comment-gen

Review the files below or copy the command above to add this skill to your agents.

Files (12)
SKILL.md
2.2 KB
---
name: comment-gen
description: Add meaningful inline comments to complex code. Use when documentation is lacking.
---

# Comment Generator

Good comments explain WHY, not WHAT. This tool reads your code, understands the intent, and adds comments that actually help future readers.

**One command. Zero config. Just works.**

## Quick Start

```bash
npx ai-comment ./src/algorithm.ts
```

## What It Does

- Adds inline comments explaining the reasoning behind complex code
- Focuses on WHY the code does something, not WHAT it does
- Supports multiple verbosity levels for different audiences
- Preserves your existing formatting

## Usage Examples

```bash
# Add concise comments
npx ai-comment ./src/algorithm.ts

# More detailed explanations
npx ai-comment ./src/utils.js --style detailed

# For junior developer onboarding
npx ai-comment ./src/parser.ts --style beginner

# Preview without changing files
npx ai-comment ./src/complex.ts --dry-run
```

## Best Practices

- **Don't over-comment** - simple code doesn't need comments
- **Focus on complex logic** - business rules, edge cases, workarounds
- **Review the output** - make sure comments are accurate
- **Update when code changes** - stale comments are worse than none

## When to Use This

- Inherited a codebase with no documentation
- Onboarding new team members
- Complex algorithms that need explanation
- Before going on vacation so others can maintain your code

## Part of the LXGIC Dev Toolkit

This is one of 110+ free developer tools built by LXGIC Studios. No paywalls, no sign-ups, no API keys on free tiers. Just tools that work.

**Find more:**
- GitHub: https://github.com/LXGIC-Studios
- Twitter: https://x.com/lxgicstudios
- Substack: https://lxgicstudios.substack.com
- Website: https://lxgicstudios.com

## Requirements

No install needed. Just run with npx. Node.js 18+ recommended. Needs OPENAI_API_KEY environment variable.

```bash
npx ai-comment --help
```

## How It Works

Reads your code file, sends it to GPT-4o-mini, and receives the same code with meaningful inline comments added. The AI analyzes control flow, business logic, and edge cases to explain the reasoning.

## License

MIT. Free forever. Use it however you want.

Overview

This skill adds meaningful inline comments to complex codebases when documentation is lacking. It emphasizes explaining why code exists and how it handles edge cases rather than restating what the code does. One command, zero config: it preserves formatting and supports verbosity levels for different audiences.

How this skill works

The tool reads your source file, sends it to a model (GPT-4o-mini) for analysis, and returns the same code annotated with concise, purpose-driven inline comments. The AI inspects control flow, business rules, and edge cases to craft comments that clarify intent and trade-offs. You can preview changes, choose verbosity styles (concise, detailed, beginner), and run in-place edits via a single CLI command.

When to use it

  • When inheriting a codebase with little or no documentation
  • Before handing off code to another developer or team
  • To clarify complex algorithms, state machines, or parsing logic
  • When preparing code for new hires or junior developers
  • Before long absences so others can understand maintenance intent

Best practices

  • Run the tool on focused files or modules, not entire repositories at once
  • Review AI-generated comments for accuracy and remove anything speculative
  • Avoid commenting trivial code; target business logic and tricky edge cases
  • Keep comments updated after refactors to prevent staleness
  • Use the preview/dry-run option before applying changes

Example use cases

  • Annotating a complex parser to explain tokenization and error recovery
  • Adding rationale to algorithm optimizations and performance trade-offs
  • Documenting workaround code for third-party library bugs
  • Preparing onboarding materials by generating beginner-friendly comments
  • Quickly auditing unfamiliar modules to speed code reviews

FAQ

Which languages does it support?

It works with common source files; the CLI preserves formatting and is language-agnostic, though experience is best with mainstream languages like JavaScript, TypeScript, and Python.

Does it change code behavior?

No. The tool only inserts inline comments and preserves the original code; use the dry-run preview to confirm changes before applying them.