Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/harmont-dev/harmont-cli/writing-interface-docblocksnpx skills add harmont-dev/harmont-cli --skill writing-interface-docblocksgit clone --depth 1 https://github.com/harmont-dev/harmont-cliWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00045 | $0.01287 |
| Opus 5 | $0.00023 | $0.00643 |
| Sonnet 5 | $0.00009 | $0.00257 |
| Haiku 4.5 | $0.00005 | $0.00129 |
Grade A, and why
writing-interface-docblocks scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 104 lines — stays where its author put it; the contents beside it link to each section on GitHub.
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 requirementrather 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.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- yesterday First seen · 104 lines · 45 tokens per session scan A 2d6a144afa9e
writing-interface-docblocks is a skill published in the GitHub repository harmont-dev/harmont-cli (21 stars, last pushed 1mo ago), licensed Apache-2.0. It adds 45 tokens to every session and 1,287 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
zuke-write-build
Write or edit a Zuke build (zuke.ts) — the code-first, strongly-typed build system for Deno/TypeScript. Use when adding or changing targets, wiring dependencies, calling a tool wrapper (DenoTasks, NpmTasks, DockerTasks, ...), generating CI, or authoring/refactoring a zuke.ts build file. For first-time project…
zuke-setup
Set up Zuke — a code-first, strongly-typed build automation system for Deno/TypeScript — in a project. Use when the user wants to add Zuke to a repo, scaffold a zuke.ts build file, install the Zuke CLI, or bootstrap the ./zuke launcher. After scaffolding, switch to the zuke-write-build skill to author targets.
ci-secure
Scans a repo's GitHub Actions workflows for the ten critical CI/CD attack vectors — template injection, fork code executed with privileges (pwn requests), cache poisoning, impostor action SHAs, secrets dumps, GITHUBENV hijack, write-token untrusted triggers, credentials in caches/artifacts, unverified remote code…
skills-registry-security
Checks the third-party security audit status of a skill published to a skills registry (skills.sh) across every cached surface, decides whether a failing finding is real or points at content already removed, and drives a stale badge to green unattended. Runs a real install to capture what users see, reads the…
sling
Diagnoses GitHub Actions failures and attributes CI time and cost using StarSling's sling CLI. Invoke this BEFORE using gh or fetching any logs whenever the user asks why a job or run failed, what made a run slow, about runner minutes or CI cost, asks to re-run or cancel a run, or pastes a GitHub Actions URL — sling…
ci-score
Grades a repository's GitHub Actions configuration against CI best practices (the CI Score: eleven pass/fail configuration facts computed from the repo's own workflow YAML) and hands back concrete fixes for every gap, ranked by impact and risk, each with an apply-now option and a paste-able agent prompt. Use when: (1)…