/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
Compatibility labels come from our tests only. Community reports add detail but cannot mark an app as tested.
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 reviewSetup 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
- Add the Skills Dugout marketplace once.
/plugin marketplace add piyush-tkd/skillsdugout - Install /comment-hygiene.
/plugin install comment-hygiene@skillsdugout - Start a new session and ask for it, for example "clean up the comments in this repo".
Not tested in Claude apps yet. These steps follow Claude apps's documented skills folder.
- Turn on code execution in Settings, under Capabilities. Skills need it.
- Download the skill zip from this page.
- Open Customize, then Skills, and choose Upload a skill. Pick the zip.
Not tested in Cursor yet. These steps follow Cursor's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add comment-hygiene --app cursor - For one repository only, run it inside the repo and add --project.
- No Node.js? Download the zip from this page and unzip it into ~/.cursor/skills/.
Not tested in Codex yet. These steps follow Codex's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add comment-hygiene --app codex - For one repository only, run it inside the repo and add --project.
- No Node.js? Download the zip from this page and unzip it into ~/.codex/skills/.
Not tested in GitHub Copilot yet. These steps follow GitHub Copilot's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add comment-hygiene --app copilot - For one repository only, run it inside the repo and add --project.
- In VS Code, turn on the chat.useAgentSkills setting.
- No Node.js? Download the zip from this page and unzip it into ~/.copilot/skills/.
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.