agentleFS
Sign inStart free
sebas8824sebas8824/sdd-harness/.claude/skills/code-commenter/SKILL.md

code-commenter

Skill1 starsChanged 3 months agoMITView on GitHub

Rules for writing, updating or deleting a code comment in any language — Java, TypeScript, SQL, YAML, shell. Use whenever the intent is to add a comment or Javadoc, revise an existing one, or decide whether one should exist at all. Enforces word budgets, the one-home rule (cite the ADR, do not re-argue it), and the principle that a change altering no behaviour alters no comment.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. Helg-git/claude-skills★ 1same name
    2. SaehwanPark/agent-skills-archive★ 1same name
    3. loskyertt/agent_skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    In the signature or the code?: Delete it.

    line 16
  2. Distinctive:

    Nowhere, and a maintainer would get it wrong without it?: Write it, once, at one site.

    line 18
  3. Distinctive:

    If you cannot state the question in a sentence, there is no comment to write.

    line 20
  4. Distinctive:

    Inline comments are not line annotations: Never narrate a single statement.

    line 41
  5. Distinctive:

    Update a comment only when the behaviour it describes changed, and then delete more than you add: a comment that has survived three edits …

    line 52
  6. Distinctive:

    TypeScript/React: no JSDoc on typed props — the type is the documentation.

    line 73

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Code Commenter

Comments are the only part of a codebase nothing verifies. They cost tokens on every read, they rot silently, and a wrong one is worse than none. Default to no comment; make each one earn its place.

The test, before you type

Name the reader's question the comment answers. Then find the answer elsewhere:

  • In the signature or the code? Delete it.
  • In an ADR or a spec? Cite the id — (ADR-0015), @spec docs/specs/… — never re-argue it.
  • Nowhere, and a maintainer would get it wrong without it? Write it, once, at one site.

If you cannot state the question in a sentence, there is no comment to write.

Budgets

Hard limits, checkable at a glance. Over budget means cut, not reformat.

CommentBudget
Class / type header< 100 words — the intent, only if the name and shape do not already give it
Method / function< 50 words — and only on genuinely complex ones
Inline, inside a bodyone or two lines, only in a high-complexity method

A comment block never exceeds the code it describes. A 25-line Javadoc over an 8-line interface is the failure this skill exists to prevent.

Where comments belong, and where they do not

  • Service and domain classes carry the explanation: the invariant, the ordering constraint, the reason a cheaper approach was rejected.
  • DTOs, records, entities, config holders, plain mappers carry none. A type that holds no logic has no why. Field-by-field Javadoc restating the field name is pure cost.
  • Inline comments are not line annotations. Never narrate a single statement. If a body needs a running commentary, the method wants splitting, not documenting.
  • Tests: name the behaviour in the test method name. A comment is warranted only to say what a passing assertion would otherwise let a reader assume wrongly.

Editing an existing comment

A change that alters no behaviour alters no comment. Moving a line, renaming a local, reformatting, extracting a helper — none of these are reasons to touch the prose. Rewriting a comment you did not have to rewrite is a diff a reviewer must read for nothing.

Update a comment only when the behaviour it describes changed, and then delete more than you add: a comment that has survived three edits is usually three explanations layered on one another.

Delete on sight:

  • Prose restating what the next line does.
  • A rationale that has been promoted to an ADR or spec since it was written — replace with the id.
  • Commented-out code. Git has it.
  • A TODO with no target. Either fix it, or record it where deferrals are tracked.

The one comment that always earns its place

A deliberate, local violation of a rule the repository states elsewhere. Without a sentence at the site, the next reviewer "fixes" it back into the defect. One sentence naming the rule and why this site is the exception — not a paragraph defending it.

Language notes

  • Java: Javadoc for the type's intent and for public contract surprises. No @param / @return that only re-says the parameter name. @spec on code implementing a spec.
  • TypeScript/React: no JSDoc on typed props — the type is the documentation. Comment a non-obvious effect ordering, a cache-merge rule, or a deliberate non-refetch.
  • SQL migrations: the header carries the why now — what the column is for, what it costs, what a reader would otherwise assume. The DDL says the what.
  • All languages: one language across the repository, per the AGENTS.md language policy.

See also

AGENTS.md (Response & Editing Style), project-code-standards.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free