mcpField
S
superior-comments

superior-comments

github.com/kodekateamDevelopment2154 installsUpdated 2d ago
Repository

About superior-comments

A code-comment guidance skill for developers reviewing or editing comments. It focuses comments on intent, constraints, and non-obvious behavior, while preserving required notices and keeping comment-only changes separate from executable code.

Key features

  1. 01Retain comments that explain intent and constraints
  2. 02Remove narration and vague TODOs
  3. 03Preserve required notices and directives
  4. 04Match repository conventions
  5. 05Verify comment-only changes

Use cases

  1. 01Cleaning noisy code comments
  2. 02Correcting stale or misleading explanations
  3. 03Reviewing comment-only patches
  4. 04Preserving API and operational documentation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/kodekateam/superior-skills --skill superior-comments

After installing, type/superior-commentsin Claude Code to confirm it loaded.

Details

From the project README

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.

Comments

Markdown supported