skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
kodekateam/superior-skills85 installs

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-comments
view source ↗

Is 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.

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>