Reviews and rewrites code comments against a why-not-what decision framework.
npx skills add https://github.com/aymansalkhatib/medledger --skill comments-aymansalkhatib
Please help me install this Agent Skill. Skill: comments Source: https://github.com/aymansalkhatib/medledger/tree/main/.claude/skills/comments Command: npx skills add https://github.com/aymansalkhatib/medledger --skill comments-aymansalkhatib
check <path> audits a file without editing, explain <symbol> proposes the minimal comment. - Use Case: While reviewing a NestJS pull request, run the check mode on a service file to list every comment violating a rule with a recommendation such as delete, shorten, or rewrite as WHY. ## Quick Start Ask the assistant to check the comments in a specific file and list which ones should be deleted or rewritten.High-intent search queries and answers about installing and using this skill.
Run the comment through the decision flow: if the what is obvious from names and types, delete it; if a better name would fix the confusion, rename instead. Keep it only when it explains a hidden constraint, invariant, or rejected alternative.
Use the check mode with a file path, for example check src/holdings.service.ts. It lists every comment violating a rule with the rule number and a recommendation such as delete, shorten, or rewrite as WHY, and makes no edits.
Six categories: non-obvious invariants, choice rationale paired with the rejected alternative, subtle semantics with a tiny example, external business or regulatory constraints, surprising behavior readers will misread, and TODO or FIXME items with a concrete follow-up.
Delete comments that restate the code, name callers or tickets, record history that git already tracks, label closing braces, restate types, contain apologies or chatter, or consist of commented-out code. A typical review removes more comments than it adds.
Use doc comments only on classes with non-obvious lifecycles, public service methods with preconditions or ordering requirements, and exported utilities with subtle input or output shapes. Never use them on DTOs, controllers, or trivial getters.
coreyjaReview code to enforce clear naming and minimal comments for complex logic.
marin-communityRuns the infra/lint catalog review on a pull request and posts findings as inline GitHub comments.
svoRefactor Python code into self-documenting structure with expressive names.
imkdwAdd JSDoc and Korean comments to TypeScript code following self-documenting principles.