comment-code

Installation
SKILL.md

Comment Code

Add comments to a source file that a competent reader would be glad of — and nothing more. The bar is high on purpose: most comments are noise, and noisy comments are worse than none, because they go stale, bury the few that matter, and narrate what the code already says. Add the ones that carry their weight, and leave everything else — including comments already doing their job — untouched.

Scope: only what you were pointed at

Work on the specific file (or files) the user named, and no others. Don't fan out to siblings, imports, or the rest of the repo because they "could use comments too" — that unasked-for sweep is exactly the churn that makes this skill annoying to use. If the target is unclear, or you were handed several files, confirm which before editing.

Two jobs — know which one you're doing

  • Commenting edits the file: you add or fix comments on the target.
  • Reviewing / checking is read-only by default: when the user asks you to check, review, verify, or look for ambiguity or clarity in comments, that is an audit, not a rewrite. Read the file, report a short list of the specific spots with a real problem (with line references), and stop. Then edit only the spots you flagged — and only after the user says go, unless the fix is trivial and unambiguous.

Conflating these is the classic failure: asked to "check for ambiguity," an agent re-processes and rewrites every comment in every file. Don't. Checking means reading and reporting; editing means changing the few things that are genuinely wrong. A request to review comments is never a licence to re-touch the whole file.

First, read and identify

Read the whole target file before writing or judging a comment — you can't tell what's non-obvious without the context. (If no file was named, ask which one.) Identify the language from its extension and syntax so you use the right comment tokens and, for public symbols, its doc convention: JSDoc /** */, Python """docstrings""", Rust ///, Go // Name …, Javadoc, and so on. Match the file's existing comment style — consistency beats your preference.

Installs
11
Repository
lelborn/skills
First Seen
Jul 21, 2026