Skills · Code

CodeSkillDugout-created

/comment-hygiene

Keeps code comments brief, factual and self-contained, without changing how the code behaves.

Created by Piyush Baheti · Source: piyush-tkd/skillsdugout/tree/main/plugins/comment-hygiene

Who it is for

Teams whose code comments have drifted into stale claims, cross-references, or leftover AI chat.

Written after reviewing codebases where comments had become notes to an AI assistant rather than to the next engineer.

When to use it

  • Before a release or a handover, to leave comments a newcomer can trust.
  • After a long stretch of AI-assisted coding left "as discussed" notes and apologies in the code.
  • When comments point to documents or tickets instead of saying what matters.

Example

You ask

Clean up the comments in src/vendor. Change comments only.

It writes a diff like this

  • // See the vendor integration notes and the earlier
  • // discussion for why we added this workaround.
  • // Omit empty arrays because the vendor rejects them.

Output is Markdown (.md), shown formatted.

Evidence

Our test

No baseline test yet. We will publish one, with and without the skill, when testing is done.

Reported by the community, by app

Claude Code: Tested
No outcomes reported yet
Claude apps: Not tested
No outcomes reported yet
Cursor: Not tested
No outcomes reported yet
Codex: Not tested
No outcomes reported yet
GitHub Copilot: Not tested
No outcomes reported yet

Compatibility labels come from our tests only. Community reports add detail but cannot mark an app as tested.

Editorial assessment · not a community rating

Editorial review in progress

We have not finished testing this listing against doing the task without it. The verdict appears here when we have. Our team made this skill; it gets the same test as external work.

How we review

Setup and customization

  • Works with no setup after install.
  • Changes comments only, and does not commit or push unless you ask.
  • Ends with a report of files reviewed, what changed, and claims it could not verify.

What it can access

Reads
First-party source, tests, scripts and configuration in the open project
Changes
Comments in those files only

Install

Claude Code: Tested
  1. Add the Skills Dugout marketplace once.
    /plugin marketplace add piyush-tkd/skillsdugout
  2. Install /comment-hygiene.
    /plugin install comment-hygiene@skillsdugout
  3. Start a new session and ask for it, for example "clean up the comments in this repo".

Community reviews

No reviews yet. Be the first to rate it after you try it.

Each review records the app, version, task and outcome; those outcomes feed the Evidence section. One rating per person; creators reply but cannot rate their own work.

No reviews yet. Be the first to rate it after you try it.

Source, license and versions

Source
github.com/piyush-tkd/skillsdugout/tree/main/plugins/comment-hygiene
License
MIT, as stated in the repository
  • 0.1.0 · 2026-10-03 · First release.
Show the full skill instructions

Comment Hygiene

Purpose

  • Keep comments useful for understanding and debugging code.
  • Explain non-obvious reasons, constraints, and edge cases.
  • Make each comment understandable on its own.
  • Avoid describing what readable code already explains.

Review scope

  • Review all first-party source code, tests, scripts, and configuration.
  • Exclude generated files, dependencies, vendor code, and build output.
  • Follow repository instructions and existing language conventions.
  • Work in batches when necessary and track coverage.
  • Never claim a complete review when files remain unchecked.
  • Apply clear comment fixes unless the user requests an audit only.

Remove

  • Comments that repeat the code or duplicate other explanations.
  • Decorative banners and unnecessary headings.
  • Conversation history: “I told Claude,” “the user requested,” “she said,” and “as discussed.”
  • Assistant apologies, self-references, and implementation diaries.
  • Unsupported descriptions such as “robust,” “secure,” or “production-ready.”
  • Cross-references such as “see above,” “see the other service,” or “refer to the document.”
  • Evidence numbers, citation markers, source line numbers, and investigation identifiers.
  • Historical counts, sample record IDs, and snapshot values from previous investigations.
  • Commented-out code with no remaining explanatory purpose.
  • Obsolete claims and completed TODOs when their resolution is verified.

Preserve

  • Non-obvious intent, business constraints, invariants, and edge cases.
  • Verified reasons for workarounds.
  • Unresolved TODOs with a clear description of the remaining work.
  • Actual domain constants, protocol numbers, and error codes needed to explain behavior.
  • Required API documentation, licenses, copyright, and attribution.
  • Compiler, linter, coverage, build, and other tool-consumed directives.
  • Legitimate descriptions of AI functionality.

Self-contained comments

  • State the relevant behavior, reason, or constraint directly.
  • Never require the reader to open another file, document, ticket, or conversation to understand the explanation.
  • Replace cross-references with the minimum verified explanation needed locally.
  • Mention another component only when necessary to explain the interaction; describe its relevant behavior in the same comment.
  • Keep a Jira ID only as optional tracking metadata when useful. The comment must remain complete and understandable if the ID is removed.
  • Preserve legally required references and functional documentation directives.

Evidence rules

  • Verify claims against the implementation, relevant callers, tests, and configuration.
  • Use evidence to establish accuracy; do not embed investigation references in comments.
  • Do not invent business intent from implementation alone.
  • Do not treat configuration as proof of production behavior.
  • Leave consequential claims unchanged and flag them when accuracy cannot be established.
  • Do not remove TODOs merely because they are old.

Writing style

  • Use plain language and direct statements.
  • Prefer one concise sentence, usually one or two lines.
  • Use short bullets for several distinct constraints or cases.
  • Avoid nested lists and long paragraphs.
  • Explain why when the what is already clear.
  • Follow existing language and documentation conventions.
  • Do not force labels or add comments to every function.
  • Preserve essential detail when shortening would change meaning.

Example

When verified:

Before:
See the vendor integration notes and the earlier discussion
for why we added this workaround.

After:
Omit empty arrays because the vendor rejects them.

Execution safeguards

  • Change comments only.
  • Preserve program behavior and unrelated user edits.
  • Avoid blanket keyword or regex deletion.
  • Treat docstrings, executable examples, and tool-consumed comments as potentially functional.
  • Report discovered code defects separately.
  • Review the final diff.
  • Run repository-required checks and relevant targeted checks.
  • Leave already clear comments unchanged on subsequent runs.
  • Do not commit, push, or create a schedule unless requested.

Completion report

  • Files reviewed and changed.
  • Main cleanup categories.
  • Uncertain claims requiring attention.
  • Excluded or unfinished scope.
  • Checks performed and verification limits.