superior-comments
Add, revise, or remove source-code comments while preserving executable behavior. Use for comment-only cleanup, documentation comments, TODO quality, and reducing narration. Do not use when the requested change modifies logic.
How do I install this agent skill?
npx skills add https://github.com/kodekateam/superior-skills --skill superior-commentsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a specialized tool for managing source code comments. It provides clear guidelines for retaining meaningful documentation while removing unnecessary noise, emphasizing the preservation of executable logic. The only detected risk is a standard surface for indirect prompt injection common to code-processing tools.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Superior Comments
Make comments carry information that the code cannot express clearly. In comment-only tasks, do not alter executable code, formatting beyond the comment, imports, configuration, or generated files.
Keep comments that explain
- intent or a non-obvious invariant;
- why an apparently simpler approach is unsafe;
- protocol, compatibility, security, or legal constraints;
- units, coordinate systems, ownership, lifecycle, or ordering assumptions;
- a workaround with enough context to remove it safely;
- a public API contract that documentation tooling consumes;
- an actionable TODO with condition, owner/reference, or concrete next step when available.
Do not remove license headers, attribution, generated-file warnings, linter directives, migration notes, or operational instructions without proving they are obsolete.
Remove or rewrite noise
- line-by-line narration of visible syntax;
- decorative separators and empty section labels;
- comments that announce the agent's workflow;
- vague TODOs such as “improve this later”;
- conclusions or signatures that mark where generated work ended;
- emoji or loud wording that adds no domain meaning;
- stale claims contradicted by the implementation.
Prefer one comment for the reason behind a coherent block over one comment per statement. Repeating the precise domain term is clearer than cycling through synonyms.
Match the codebase
Preserve the repository's language, comment syntax, documentation format, and normal tone. Keep comments close to the behavior they constrain. When a comment is wrong but the code is in scope only for reading, correct the comment to describe current behavior; do not silently change the behavior to match it.
Verify
Review the diff and confirm that only comments changed. Run a narrow formatter or parser only when comment syntax can affect compilation, generated documentation, directives, or tooling. Report any ambiguous comment you preserved because its operational role could not be disproved.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/kodekateam/superior-skills/superior-comments">View superior-comments on skillZs</a>