Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Code Comments: Cut the Noise, Keep the Why

    1

    Stop your agent writing `// increment i` and start it writing the comments only it can write: why the obvious fix is wrong, where copied code came from, which spec forces an oddity, how a bug reproduced. Three tests before a comment ships, plus an audit that reports keep, delete or stale per line.

    $5

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    Code Comments: Cut the Noise, Keep the Why

    Code Comments: Cut the Noise, Keep the Why

    Example session with this skill installed

    Audit the comments in src/billing/invoice.ts. Tell me which to keep, which to delete, and what's missing. Don't change the file yet.

    • Read your context and instructions
    • Compiled the code comments

    Comment audit: src/billing/invoice.ts

    I read the file, src/billing/tax.ts, and all three commits (git log -p, git blame). The file is unchanged.

    src/billing/invoice.ts:3      delete   "LineItem interface" repeats the declaration right below it
    src/billing/invoice.ts:7      keep     the reason for integer cents (summing floats drifts) is a rule the code can't state. "price in cents" repeats the field name and can go
    src/billing/invoice.ts:20-28  delete   "Builds an invoice" repeats the function name, and each @param/@returns just repeats the parameter name. It says nothing the signature doesn't
    src/billing/invoice.ts:30     delete   a "Step 1" label
    src/billing/invoice.ts:31     delete   describes the reduce on the line below
    src/billing/invoice.ts:33     delete   a "Step 2" label that describes the call below
    src/billing/invoice.ts:35     delete   describes the if-statement below. The real reason is missing (see :36)
    src/billing/invoice.ts:36     missing  the negative-tax clamp is a workaround with no reason given, and someone could "tidy" it away
    src/billing/invoice.ts:46     stale    says 14 days, but the code adds 30
    src/billing/invoice.ts:47     fix the code instead   30 * 24 * 60 * 60 * 1000 is an unnamed number. A named constant for net-30 terms would explain it
    src/billing/invoice.ts:20-29  missing  buildInvoice is exported but its contract isn't written down: amounts are in cents, total = subtotal + tax, tax is never negative, due date = issuedAt + 30 days
    

    Keep: 1 comment (line 7). Delete: 6 (lines 3, 20–28, 30, 31, 33, 35). Stale: 1 (line 46).

    What's missing, and why it matters most

    Line 36, the tax clamp. The reason is only in the message of commit 9a87c40, not in the file:

    The tax provider returns a negative amount for customers with an expired exemption certificate instead of an error (support ticket #4471, confirmed by their support on 2026-03-12). Charging negative tax refunded customers on every invoice. Clamp until the provider fixes it; remove once their v3 API is live.

    That message says what broke, when it happens, the ticket number, and when the code can be removed. It should go at line 36 in place of the comment on line 35, ideally as a TODO(owner): tied to the v3 API. The repo doesn't record an owner; Dana is the commit author. It also has no URL for ticket #4471, so the comment should give the ticket number without a link.

    Line 46, the due date. The comment has been wrong since it was added in 66f4df8. The 30 dates from the first commit, adad80c, titled "billing: build invoices with net-30 due date", so the code matches what was intended and the comment doesn't. Replace it with the rule behind the number (net-30 terms), best done by naming the constant. The repo doesn't say where the net-30 policy comes from, so the comment shouldn't claim a source.

    Outside the comment audit (noted, not checked further)

    • Line 47 adds a fixed 30 × 24 hours in milliseconds, not 30 calendar days. If due dates are shown in a local time zone that observes daylight saving time, the result may be off by an hour. I haven't confirmed that this matters here.
    • Line 7 says "never a float", but the field is typed number and nothing in the code checks it.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    The problem

    AI agents over-comment in the cheap direction and under-comment in the expensive one. They narrate every step (// Step 1: validate input, // Added null check) and almost never record what they learned while making the code work: the undocumented null, the header a vendor API silently needs, the retry count found by trial. That context dies with the session.

    What it does

    • Runs three tests on every comment before it ships:
      • Delete: does it say anything the code doesn't?
      • Surprise: would a competent reader "simplify" this into a bug?
      • Archaeology: did you learn something that isn't in the file?
    • Keeps only the six things code cannot say: a non-obvious choice, where copied code came from, an external spec, a bug's reproduction condition, unfinished work (TODO(owner):), and the domain rule behind a magic value.
    • Bans comments that restate code, narrate structure or the diff, prop up a bad name, or invent a reason.
    • Re-reads the comments around every edited line, because comment rot comes from edits, not time.
    • Audits existing files with one line per finding: file:line, verdict (keep / delete / fix the code / stale / missing), and a reason.
    • Follows the codebase's comment language, whether that is English, Thai or anything else.

    What's inside

    • SKILL.md: the tests, the six categories, core rules, and two lanes (writing and auditing)
    • references/comment-smells.md: the full anti-pattern checklist
    • references/comment-shapes.md: worked examples of each of the six categories
    • references/doc-comments.md: what a doc comment on a public interface must carry

    Frameworks & tools

    Language-agnostic: Rust, Go, TypeScript, Python, SQL, Bash, HCL and config files.

    Why this beats prompting it yourself

    "Write fewer comments" makes agents delete the valuable ones too. This skill targets information, not volume, and adds rules aimed at how agents fail: never invent a "why", paste only URLs you actually opened, and never comment code you don't understand. Its base rules come from Stack Overflow's published best practices on code comments; the skill states which rules are its own additions.

    Use cases

    • Making an agent's code reviews and PRs less noisy.
    • Cleaning up an over-commented file.
    • Making sure a workaround or bug fix carries its reason.
    • Writing doc comments for a public API.

    Known limitations

    It covers source comments only. It does not generate API documentation sites, READMEs, commit messages or PR descriptions, and it is not a full code review.

    Source comments only. It does not generate API documentation sites, READMEs, commit messages or PR descriptions, and it is not a full code review. It never invents a reason: when the why is not in the code or its history, it says so and asks.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 8 days ago

    Permissions

    Read Files
    Write Files

    Read is used to read the files you point it at and, in audit mode, their git history. Write is used only when you ask it to add, fix or delete comments. The skill ships no scripts and makes no network calls.

    Listed8 days ago

    What's inside

    Frequently Asked Questions

    No. It deletes comments that repeat the code and adds the ones that carry context the code can't hold. It judges each comment by what it says, not by how many there are.

    Yes. The tests ask about information, not syntax. It also follows the codebase's comment language, English, Thai or anything else.

    Yes. Audit mode reports one line per finding (file:line, verdict, reason) and does not change the file unless you ask.

    It says what it observed instead of writing a reason. Never inventing a "why" is a core rule, because a confident wrong reason costs more than no comment. If you or your repo's history give it the reason, it writes that down.

    Yes. references/doc-comments.md sets what a doc comment on a public interface must carry, so @param lines that only repeat the parameter name get flagged.

    No. It is instructions and references only, with no scripts and no network calls.

    New in Code Quality & Review