petarzarkovpetarzarkov/dunx/.claude/skills/docs-pass/SKILL.md

docs-pass

Skill93 starsChanged 4 months agoMITView on GitHub

Revise one documentation file so it states facts instead of performing insight, and get it under the budgets in scripts/no-slop.test.ts. Use when writing a new guide or README, when a reader reports the docs read like AI output, or when `bun test scripts/no-slop.test.ts` fails.

1 other project uses a version of this.

Adopted by

Most recently taken up by

Aximande/agent-skillstheir own version, first seen Sep 18, 2026

Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
Aximande/agent-skills★ 4same 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 repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- coverage-reportSkill
- new-packageSkill
- releaseSkill
- spikeSkill
- whats-nextSkill

The file

We split this skill into the rules it gives an agent

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

≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Delete outright, without replacement:
line 23
Distinctive:
Run the guard. Note the file's mode and its three counts.
line 93
Distinctive:
Read the whole file first.
line 94
Very specific:
Check the rendered result if the file is under docs/: bun run docs:build regenerates internal/docs/src/generated/.
line 99
Very specific:
Do not add frontmatter to anything under docs/.
line 104
Very specific:
Do not renumber or rename a guide casually.
line 107
Distinctive:
Do not add a file to the guard's Exempt list to make it pass.
line 111
Very specific:
Do not touch the em dash rule's territory.
line 112

≈ “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

/docs-pass

One file per invocation. The guard is scripts/no-slop.test.ts; it owns the mode map and the budgets, and this skill is how a file gets under them.

bun test scripts/no-slop.test.ts    # names every file, its mode, and what it blew

The rule that does the work

Cut. Do not rewrite. Asking for a rewrite produces different prose at the same length, and the length is the defect. Every pass should shrink the file. A paragraph that survives three deletions and still says the same thing was three sentences long.

Delete outright, without replacement:

Any sentence that tells the reader what the previous sentence meant.
Any sentence about the design's virtue rather than its behaviour. Move it to docs/architecture/ if the reasoning is genuinely load bearing, or lose it.
Any restatement of what the code block above already shows.
Any sentence introducing the next sentence.

Modes

Set by path in the guard's MODES table, first match wins.

Mode	Holds	Writes
Tutorial	`guide/02-first-steps.md`	One path through, in order, every step runnable. No alternatives, no asides
Reference	the rest of `guide/`, every published `README.md`	Signature, behaviour, failure mode. Tables over paragraphs. No narrative
Explanation	`docs/architecture/*`, `guide/01-introduction.md`	The decision, the alternative, the measurement. This is where reasoning belongs

A Reference page that wants to explain why links to the Explanation page. It does not explain in place.

Published or repo-only

docs/ holds user documentation and the maintainer's decision record. Only the first is on the site, and PUBLISHED_REFERENCE in internal/docs/scripts/generate.ts is the list.

On a published page, none of the following may appear: a private workspace (internal/*), a roadmap file, CLAUDE.md, a packages/*/src/ path, a repo script, or a sentence addressed to whoever maintains dunx. internal/docs/src/published-voice.test.ts enforces it.

Say @dunx/http's lifecycle suite, not packages/http/src/server/lifecycle.test.ts. Cite a measurement when a reader would change their code over it; put the decomposition behind it in docs/architecture/, which the site does not publish.

What the guard measures

Three sentence shapes, budgeted per 100 prose lines because each is fine occasionally and the defect is density. Measured against this repo before they were picked: the generic AI vocabulary that circulates online scored 1 hit across all of docs/, and these three scored 628.

Shape	Looks like	Fix
antithesis	"Colour encodes the runtime, not the ranking"	State what it does. Drop the correction
closer	"which is why", "that is the point", "is exactly what"	Delete the clause. The reader drew the conclusion
knowing	"deliberately", "by design", "the reason is"	Delete, or move the reasoning to `docs/architecture/`

Plus a paragraph length cap, which is the wall-of-prose axis, and a zero tolerance list of marketing words and announcement sentences.

Fixing a budget failure by moving prose into a bullet list passes the check and fails the intent. Lists are excluded from the paragraph measure so that reference material stays in tables, not so prose can hide.

Voice

Assume a senior TypeScript developer. Never explain DI, HTTP or decorators as concepts. Explain what dunx does differently.
Imperative. "Register this with" over "This can be registered by".
Facts carry numbers. "55 ms boot" over "fast boot". If there is no measurement, there is no adjective.
Open with a code block or an imperative sentence. Never with orientation.
Inline comments inside a snippet beat a paragraph under it.

Procedure

Run the guard. Note the file's mode and its three counts.
Read the whole file first. Most offences are one paragraph doing a job a table does better.
Cut top to bottom. Convert prose runs to tables where the content is genuinely tabular.
Re-run the guard on that file.
Check the rendered result if the file is under docs/: bun run docs:build regenerates internal/docs/src/generated/.

Do not

Do not add frontmatter to anything under docs/. The site generator does not strip it (internal/docs/scripts/content.ts), so it renders as literal text. The mode map lives in the guard instead.
Do not renumber or rename a guide casually. The NN-name.md prefix is the nav order and the slug source in internal/docs/scripts/generate.ts, and published #/guide/* URLs depend on it.
Do not add a file to the guard's Exempt list to make it pass.
Do not touch the em dash rule's territory. no-em-dash.test.ts still applies.

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