Human Readable Reports — AI skill for Claude Code

human-readable-reports

**Your coding agent writes reports that are technically correct and unreadable.** Walls of jargon, `file:line` dumps, telegraphic bullets, invented terms. The team stops reading. This skill fixes that — deep content, easy reading.

   [](https://ko-fi.com/riversound)


---

The problem (you're not imagining it)

"AI verbosity" and "AI slop" are now common complaints — LLMs are trained to write long, thorough, hedged answers, so their reports default to something only the author's other agent could love. When the doc is unreadable, **the human becomes the bottleneck.**

The fix, in one look

**Before** — what an agent writes by default:

parseInput() is O(n²) due to nested scan (utils.js:88);
latency scales quadratically with list size → UI jank at scale.

**After** — same finding, with this skill:

**The input parser gets slow as the list grows.** It re-scans the whole list for each item, so a long list makes the screen stutter. *(code location in the notes below)*

Same facts. One of them your team will actually read.

For a whole report shown both ways, with the rule behind each change, see [`examples/`](./examples/): a flaky CI test write-up, before and after.

The 14 rules

1. Reader-first — name the reader before writing; by default, a junior dev who wasn't there.
2. Point first — each section opens with the takeaway in one plain sentence.
3. Concrete before abstract — one plain picture for a new concept; the real sequence of events for a cause or change.
4. Full sentences, not fragments — bullets for parallel items, sentences