harmont-cli: Skill for Claude Code

Writing Interface Docblocks

Overview

A docblock is a contract, not a transcript and not a changelog. It tells a caller — who has never seen the body, and never saw your prompt — what the thing IS and how to use it. Terse. Present tense. Timeless.

If the reader could learn it by reading the body, the docblock does not repeat it. If the reader only knows it because they saw your conversation, the docblock never mentions it.

Violating the letter of these rules is violating the spirit.

The one test

Before writing any line, ask: does a caller need this to use the function correctly, without reading the body?

• Yes → it belongs (purpose, params, return, errors, invariants, caller constraints).
• No → delete it.

Belongs vs excluded

Belongs (the interface)	Excluded (the implementation / the transcript)
What it does, in one line	Step-by-step of how it does it ("proceeds as follows: 1, 2, 3")
What params/return mean	Restating the signature or types already visible
When it errors/panics (the when)	Why you chose errors over panics; internal mechanism
Caller-visible invariants & constraints	Private fields, helpers, backing arrays, Big-O of the body
Non-obvious usage caveats	Analogies to what the code "is like"

Never leak the prompt

The doc describes current behavior as if it always existed. It has no memory of your task.

Ban these — they mean you are documenting the conversation, not the contract:

• as requested, as required, to satisfy, per the requirement
• rather than X, instead of X, now returns, changed to — no comparison to old/alternative behavior
• Parroting a constraint you were given: asked "must never panic" → do not write "this never panics." State the contract (# Errors: returns ... when ...); absence of panic is implied by the return type.

Terse by default

Most functions need 1–3 lines. Reach for more only when a caller-facing caveat genuinely requires it. A docblock longer than the body of a simple function is a smell.