Skip to content
Skills Library
Programming · Writing

code-comments

/code-comments

What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages.

Licence
MIT
Last repository change
09.11.2026

Assessment and security

85/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content20 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages.

Original author description

What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages.

How it works

  1. Find the rule for what you are changing
  2. Two hard rules
Original SKILL.md headings · 27 lines, 364 words
SKILL.md preview
---
name: code-comments
description: What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages.
---

# What a comment should say

One test decides it: **if this comment disappeared, what would a reader lose?** If the answer is nothing, delete it. Anything the code already says stays out of comments — when a name, a structure or a type makes it clear, renaming, extracting a function or splitting a branch beats a comment, and that work belongs inside the current change without widening its scope. A comment earns its place by carrying what the code cannot: why it is done this way, where the constraint comes from, where the edge sits.

Declarations that other code calls into get block comments (JSDoc / TSDoc, docstrings, Go doc comments) so hovers and completion can show them; implementation detail and inline logic get `//`. Comment language follows the comments already in the file; a new file follows the dominant language of its directory or repository, and one file never mixes two languages.

## Find the rule for what you are changing

| What you are changing | Read |
| --- | --- |
| Config files of any kind: build, lint, CI, deploy, environment variables, container orchestration | [references/config.md](references/config.md) |
| interface, type, enum, field semantics | [references/types.md](references/types.md) |
| Constants, magic values, enum values, defaults | [references/constants.md](references/constants.md) |
| Functions, methods, hooks, components, exported APIs | [references/functions.md](references/functions.md) |
| Branches, loops, multi-step flows, test cases, workaround logic | [references/inline.md](references/inline.md) |
| Markers for pending work, temporary logic, deprecation, commented-out code | [references/markers.md](references/markers.md) |

A file header says what the file is responsible for and who calls it, in one line; read only the references listed above that you need, never all of them.

Decide whether something is config by who reads it, not by its name: build, lint, CI, deploy, container and runtime readers make it config (`.prettierrc.mjs`, `vitest.workspace.ts`, `Makefile`, `.env.local`, `nginx.conf` all count); anything imported by product code is source.

## Two hard rules

- An old comment is either made correct or deleted. A comment that reads right but is no longer true does more harm than no comment.
- Leave no liabilities: commented-out implementations, debug leftovers and change logs all go. Their home is the commit history.
Files in this package (8)
  • SKILL.md 3 KB
  • agents/openai.yaml 1 KB
  • references/config.md 5 KB
  • references/constants.md 2 KB
  • references/functions.md 4 KB
  • references/inline.md 4 KB
  • references/markers.md 2 KB
  • references/types.md 2 KB

Versions

RepositoryScoreLicence
This page · zn-craft/agent-skills85MIT
zenobi-us/dotfiles100MIT
rp1-run/rp1100Apache-2.0
petekp/claude-code-setup100MIT
portabletext/editor100MIT
caidanw/skills100MIT
caidanw/skills100MIT
izumin5210/dotfiles95MIT
overmind-core/overmind90AGPL-3.0

Database snapshot: 13.11.2026 · package version 87971800ab76 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100comment-hygiene
    Curate source-code comments and docstrings — delete AI-slop and stale comments, keep only the non-obvious WHY, and never change executable code. Use when cleaning up comments/docstrings, during a samocode cleanup or quality-review step, when running /comment-hygiene, or when…
  • 90no-comments
    Delete the comments in a diff that the code should make unnecessary, through a fresh read-only reviewer, then fix the code each deleted workaround comment was excusing. Use before a change goes to review, or when the user asks to strip comments from a diff.
  • 100address-pr-comments
    Address PR review comments by fixing code, replying to each comment, and re-requesting review. Use this skill when the user wants to handle, fix, resolve, or address PR feedback, review comments, or code review suggestions. Also use when the user says things like "fix the PR…
  • 100code-comment-style
    Write and tighten code comments so they state the why or the invariant in 1-3 lines. Use when adding comments to code, or when pruning verbose comments in a diff or PR.
  • 100comment-review
    Review and improve the code comments a PR or branch adds, against the standard in docs/developer/CODE_COMMENTS.md: cut the ones that restate the code, tighten the verbose ones, reframe what-comments into the why or the constraint, and add the contract docs the change left…
  • 100comments
    Comment rules for every language: which comments survive, format, protected comments, placement, TODOs. Use when writing, editing, moving or deleting comments, docstrings or TODOs. Auto-invoke when editing code files.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.