Skip to content
Skills Library
Programming · Writing

code-comment-discipline

/code-comment-discipline

Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.

Repository
hedgehog ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 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.
Content35 / 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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.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

Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.

Original author description

Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.

How it works

  1. Default: no comment
  2. When a comment is allowed
  3. What a comment must never say
  4. Applying to existing comments
Original SKILL.md headings · 44 lines, 301 words
SKILL.md preview
---
name: code-comment-discipline
description: Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.
---

# Code Comment Discipline

Well-named identifiers and clear structure explain what code does. A
comment earns its place only when it explains something the code cannot:
a hidden constraint, a non-obvious invariant, a workaround for a specific
external bug, or behavior that would surprise a reader.

## Default: no comment

Most lines, functions, and blocks need zero comments. Before writing one,
check whether the same clarity is reachable by renaming a variable or
function instead — prefer that over a comment every time.

## When a comment is allowed

Only for the non-obvious:

- A constraint imposed from outside the code (an API's undocumented
  limit, a browser quirk, a platform requirement) that isn't visible at
  the call site.
- An invariant the code relies on that isn't implied by types or names
  (e.g. "callers must hold the lock before this runs").
- A deliberate workaround for a specific bug in a dependency, with enough
  detail to know when it's safe to remove.
- Behavior that looks like a mistake but is intentional.

## What a comment must never say

- What the code does — that's the identifier's job, not the comment's.
- Why *this* task needed the change, who asked for it, or which ticket,
  issue, or conversation prompted it.
- History: "used to be X," "changed from Y," "removed Z," "previously,"
  "now we," or any other before/after narration. A comment states the
  current state and its non-obvious reason only, never how it got there.
- A restatement of the function/variable name in prose ("increments the
  counter" above `counter++`).

## Applying to existing comments

When editing a file that already has comments violating these rules,
remove or rewrite them as part of the same change rather than leaving
them in place — don't let a nearby edit normalize the pattern.

Versions

The database has no other skills named code-comment-discipline.

Database snapshot: 13.11.2026 · package version 5b9af566c48d (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

  • 84document-code
    Decide whether a comment belongs, and write the ones that do — in Ruby, YAML, a Dockerfile, a shell script, tests or config. Use it before adding any comment, docstring or YARD block, including one you are about to write mid-implementation, and before deleting or rewording one…
  • 100lean-comments
    Audits, writes, and refines maintained first-party source-code comments and declaration-level documentation across languages. Use when adding, editing, reviewing, cleaning up, or auditing comments, doc comments, docstrings, TODO, FIXME, NOTE, suppressions, or other source…
  • 100pr-comment-reply
    Render the canonical reply text for a PR review comment. Use when drafting, writing, or posting a "PR comment reply", "review comment reply", "reply to this comment", "respond to this review comment", "answer the reviewer", "reply on the PR thread", or any text bound for `gh…
  • 100appropriate-comments-code
    Use when writing, editing, or reviewing code in any language and about to add, change, or review a comment, docstring, doc comment, or TODO — especially one that narrates history or a past attempt, restates the line below, explains a feature rather than the code, tells a future…
  • 85code-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.
  • 100pr-comment-review
    This skill should be used when the user asks to review a GitHub pull request AND post the findings as a comment on the PR ('review and comment on PR', 'review PR roi comment len do'). Multi-agent confidence scoring, threshold 80/100, posts via gh. For local working-tree review…

Feedback and reports

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