comments

Installation
SKILL.md

No Comments in Source Code

Do not add comments to application or test source code except for the OpenAPI JSDoc below. This is a prohibition, not a preference for fewer comments. An existing comment style does not authorize new comments.

Scope

  • Prohibit inline and block comments, file headers, section dividers, TODO/FIXME notes, commented-out code, and documentation comments or docstrings, except for the OpenAPI exception below.
  • Deployment files, operational scripts, configuration, and standalone documentation are outside this prohibition. Classify by purpose, not file extension; application code does not become exempt by calling it a script.
  • Express behavior through clear names, straightforward structure, types, and meaningful tests. Do not add abstractions or split functions solely to replace comments.
  • Most code needs no explanation. Record only exceptionally important constraints or decisions worth preserving long-term in the existing spec. Do not document every implementation detail or move every removed comment into the spec. Complexity or a useful explanation of "why" is not an exception.

Existing Comments

  • Daily work: follow the no-new-comments rule. Loading this skill or fixing a bug is not project-wide adoption; keep existing-comment cleanup within authorized task scope. An unadopted project does not acquire a new lint gate merely from skill loading.
  • Authorized adoption: explicit user authorization or project instructions must enable the project-wide policy. Reuse existing authority without asking again. Remove all prohibited application/test comments across the project, not only changed files, without a legacy baseline; preserve OpenAPI JSDoc and move any executable coverage into ordinary tests. Removal alone does not require a spec entry; retain only exceptionally important long-term constraints/decisions there.
  • Already adopted: preserve and maintain the project's cleanup/enforcement requirements; routine work does not reset or weaken them. Repair enforcement within authorized write scope. Read-only work reports violations and missing enforcement without edits; it neither adopts the policy nor invents a gate.

OpenAPI Generation Exception

Installs
14
Repository
noih/dev-skills
First Seen
Apr 29, 2026