Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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.

KodekaTeam · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add KodekaTeam/superior-skills --skill superior-comments

About this skill


name: superior-comments description: 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.

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.