An Agent Skill that keeps a source-code comment only when it carries information the code and its context cannot.
Important
This skill deletes comments. It shortens and rewrites the ones that earn their place, and removes the rest rather than rewording them. If you want your existing comments polished where they stand, this is the wrong skill.
- 🧹 No comment by default: Requires a reason to add a comment rather than a reason to remove one.
- 🧭 Necessity before wording: Settles whether a comment should exist before touching how it reads.
- ✂️ Deleted, not polished: Removes an obvious comment instead of rewording it into something tidier.
- 🚫 No invented rationale: Refuses to invent a security, performance, or compatibility reason for keeping a comment.
- 🔁 Code over comment: Renames a local or extracts a named boolean when that removes the need for one.
- 📐 Documentation, not coverage: Documents a declaration for its contract, never merely for being exported.
- 🌐 Every comment form: Applies one test to line comments, doc comments, docstrings, and file headers.
- 👣 Durable state only: Describes the code at HEAD, never the diff, the pull request, or the review thread.
- 🏷️ Dead commentary: Drops stale TODO, FIXME, and HACK markers, and commented-out code that serves no purpose.
- 🔒 Protected directives: Preserves lint, compiler, and license comments, and drops a tooling directive only once proven obsolete.
- 📜 Your rules win: Honors documented repository requirements, public API documentation contracts, and tooling rules.
- 📋 Repository audits: Sweeps a whole repository on request, then checks the diff against a 17-item acceptance list.
- 🎯 Scoped diffs: Touches maintained first-party code only, and skips generated and vendored content.
Install the skill with the skills CLI:
npx skills add JonathanXDR/lean-commentsThe CLI asks whether to install into the current project or globally for your user. Pass -g to skip the prompt and choose global. Global scope applies the policy to every repository you work in, so choose the project scope to keep it to this one.
SKILL.md uses only fields from the specification and no vendor extensions, so any compatible client can load it. The client showcase links setup instructions for each client.
To install by hand, put SKILL.md in a directory named lean-comments under your agent's skills directory. The specification requires the directory name to match the name field.
Ask for comment work in plain language. The skill activates on requests to add, edit, review, clean up, or audit comments, including doc comments, docstrings, TODO, FIXME, NOTE, and suppressions. Claude Code also takes /lean-comments to invoke it explicitly, and other clients have their own form. Any of these reaches it:
/lean-comments audit the comments in src/
Clean up the comments in this diff.
Is this docstring worth keeping?
Are there stale TODOs in this file?
It also applies while you write code, so a new comment has to pass the same test before it lands. The skill reviews the comments your change touches and does not start a repository-wide cleanup unless you ask for one.
Before keeping or adding an ordinary comment, imagine it gone and ask:
Would a competent maintainer lose meaningful, non-obvious information if this comment did not exist?
If no, it goes. If uncertain, it goes unless repository evidence shows the information matters. If yes, only the minimum stays.
None of this saves a comment: being correct, harmless, already present, well written, phrased as a warning, security related, or attached to an export. Only the information does.
The skill deletes narration rather than rewording it, because the code already says the same thing:
// Return the normalized result
return normalize(result);A constraint the code cannot show stays, as long as the implementation or an external contract backs it:
// Preserve source order because the upstream API matches items by positionThe skill deletes a label on a declaration outright, neither shortening it nor promoting it into documentation:
// A watchlist row
export interface WatchlistItem {
media: Media;
added_at: string;
}Whatever the delimiter, a single-line prose comment carries no terminal punctuation, so // Preserve source order is correct and // Preserve source order. is not. It opens with a capital unless a technical literal starts the line. Multi-sentence declaration documentation is exempt and uses ordinary sentence punctuation.
The skill takes every ordinary comment, existing or proposed, through this order:
| Order | Outcome | Applies when |
|---|---|---|
| 1 | Delete or omit | The information is already clear without it |
| 2 | Express through code | A tiny behavior-preserving readability change removes the need for it |
| 3 | Shorten | It is necessary but carries unnecessary information or words |
| 4 | Rewrite | It is necessary but unclear, inaccurate, stale, awkward, or inconsistent |
| 5 | Use declaration documentation | The information belongs to the declaration's contract, semantics, or intended usage |
| 6 | Keep unchanged | It is already necessary, minimal, accurate, durable, and correctly styled |
The order is the point. The skill settles necessity before wording, so an unnecessary comment is never polished into a better unnecessary comment, and never promoted into documentation to justify keeping it.
Some comments sit outside that order because their presence, position, or exact syntax carries meaning. Shebangs, lint and formatter directives, compiler and coverage directives, build tags, generated markers, and license headers keep their syntax exactly as written. A tooling directive holds that protection only while it is still required, and loses it once the repository or the tool proves it obsolete. Generated, vendored, and third-party files stay out of scope entirely. Comment-like text inside string literals, regular expressions, snapshots, and fixtures is data, not commentary.
- This is judgment encoded as rules, not a linter. Two runs over the same borderline comment can disagree.
- A comment whose reason the skill cannot find gets deleted, so keep the reason where the skill can reach it. The issue tracker counts as evidence, closed tickets included, so point it at the ticket. Rationale that lives only in your prompt or someone's memory will not save a comment.
- Every worked example is TypeScript. The rules are language agnostic and name JSDoc, TSDoc, JavaDoc, KDoc, Rust and Go doc comments, C# XML documentation, and Python docstrings, but you will not find your own syntax demonstrated.
Validate SKILL.md against the reference library from the Agent Skills specification repository. The published package is named skills-ref while the executable inside it is named agentskills, so the command names both:
uvx --from 'skills-ref==0.1.1' agentskills validate "$PWD"Pass $PWD rather than ., because the validator compares the last segment of the path against the name field and . gives it nothing to compare.
The validator reads the frontmatter and stops there, so it says nothing about the specification's size guidance. By the rough estimate below, SKILL.md already sits near the 500 line guidance and past the 5,000 token one. Measure both before adding to it, and expect to cut something in exchange:
grep -c '' SKILL.md # lines, guidance 500
awk '/^---$/{c++; next} c>=2' SKILL.md | wc -c # body chars, roughly 4 per token against a 5,000 token guidance- 📖 Read
SKILL.mdfor the complete rule set, including the audit procedure and its acceptance check. - 🧩 Read the specification if you want to package a skill of your own.
- 🐛 Hit a bug or have an idea? Open an issue.
Licensed under the MIT license © Jonathan Russ.