# Craft Comment

> What a comment is for, what shape it takes, and the space around code that means no comment is needed. Applies to any language, not only shell.

- Skill: `attac-t/craft-comment` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add attac-t/craft-comment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/attac-t/craft-comment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: attac-t (https://skillmd.com/u/attac-t)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/attac-t/craft-comment

---


# Skill: Craft Comment

> "A comment you had to write is a name you did not."

**The rule in one sentence: a comment of three lines makes each line three bytes shorter than the
one above it.** One line and two lines are fine and are not graded. `bin/taper.sh` grades this
repository's own comments; elsewhere it is craft.

## The Standard

1. **Carry a discovery, never narration.** `# herd start stops the data services` earns its line.
   `# ── Step 3 ──` above a line printing "Step 3" does not.
2. **Needing one is evidence against the code.** A comment explaining *what* a body does means the
   name is wrong or the body is two jobs. Fix that first and the comment leaves on its own. A
   preamble longer than what it introduces is the clearest form of the tell.
3. **One sentence, when one sentence does it.** No fence and no bold — the blank line already
   separated it, and the sentence that matters goes first.
4. **Three lines, each exactly three bytes shorter than the one above it.** Not *about* three, and
   not an even step of any size — three, twice. A block that steps by eighteen is a triangle, and a
   triangle is what this refuses. `taper.md` carries the loop.
   **Two lines when three will not land honestly.** Padding a sentence to reach the number is the
   waste `economy` names, wearing craft — and a two-line comment is not graded, because rule 3
   already prefers it. What is never allowed is a three-line block that misses.
5. **Let it breathe.** Blank lines inside a body group steps into thoughts, so it reads as three
   moves rather than eleven lines. A body with no blank line is held breath.
   **Breathing is space, not words** — the opposite mistake is filling the space that was doing the
   work.
6. **A split moves its comments.** After extracting, the parent keeps only what the parts do not say.
   Facts left behind get read twice and edited once.
7. **Say why a defensive line survives.** A guard with no reason reads as redundant, and redundant is
   what gets simplified away.

## Examples

See [taper](taper.md) for the loop, and [comments](../craft-sh/comments.md) for before and after.