- Home
- Skills
- Code Quality & Review
- Code Comments: Cut the Noise, Keep the Why
Works with the AI Agents you already use
Code Comments: Cut the Noise, Keep the Why
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
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
numberand 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 checklistreferences/comment-shapes.md: worked examples of each of the six categoriesreferences/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
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
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 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 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.