Importing your OpenAPI spec doesn't document your API. It builds a skeleton and stops.

I ship a lot of packages. Every one needs API docs, and for a while I did what everyone does: point a tool at the OpenAPI spec, let it generate a reference, call it done.

It isn't done. An import gets you a skeleton — and then it stops.

What the importer actually gives you

Point a good importer at a spec and you get a real reference section: one page per tag, every endpoint, its params and response codes, and code samples in cURL, Python, JavaScript, and Go. That part is genuinely useful, and I'm not going to hand-roll it.

But read what comes out and it's thin. No response example bodies — even when the spec carries an examples block. No error resolutions — just 409 — conflict, never what a developer actually does about it. The samples are shaped right and empty inside.

And it trusts the spec completely. I pointed the importer at a real client API — VayaPin's live spec at api.vayapin.app. The spec had no servers block. So the importer did the only thing it could: it defaulted every base URL to https://api.example.com. Every code sample, every "try it" call, aimed at a host that doesn't exist. It would have shipped, looked complete, and quietly sent every developer to the wrong place.

A whiteboard sketch: an openapi.json spec with no servers block, and the resulting code sample where api.example.com is struck out and corrected to api.vayapin.app — caught before it ships.

Catching that is the whole point of a skill that knows what it's looking at.

A reference is one of four docs

The deeper issue: a reference isn't documentation. It's one quarter of it.

A whiteboard sketch of the Diátaxis grid — Tutorial, How-to, Reference, Explanation — where only the Reference quadrant is filled in and checked. Caption: importer writes 1 of 4.

Diátaxis — the framework the best docs teams use — splits developer docs into four jobs. Tutorial: get me to my first success. How-to: help me finish a specific task. Reference: tell me exactly what this endpoint does. Explanation: help me understand why it works this way. An importer writes Reference. The other three — the ones a developer reaches for when they're stuck — it skips.

So a real doc set is: import the reference, then enrich it. Add the response examples and error resolutions the importer dropped. Write the tutorial, the how-tos, the explanation. That is the work. And it's exactly the work I kept doing inconsistently, by hand, package after package.

So I built the skill that does it

@di-atomic/api-docs-writer is guidance-only. It doesn't render anything itself — it decides the structure and enforces the quality, then hands delivery off. What it knows:

The four quadrants. It imports the reference, then tells me which of the other three docs this API needs and writes them in the calm, precise register technical docs live in.
What good looks like per method. Every method gets at least one runnable example. Every fallible method gets an error section with resolutions, not just status codes.
The render targets. A package README doesn't render the same on npmjs, Verdaccio, and GitHub Packages — relative image paths break on one, keywords drive search on another. The skill carries the three fingerprints so a page never ships blank.

And it doesn't take my word for any of it.

Scripts that can't lie

The part I trust most is the enforcement. verify-diataxis-coverage fails if the set is missing a quadrant. verify-example-per-method fails if any method has zero runnable examples. verify-error-taxonomy fails if a fallible method lists no errors. verify-registry-render lints the README against the target registry's real gotchas. Each returns PASS or FAIL with numbers, not vibes. A doc set that "looks complete" but fails one of them is not done — and the script says so, out loud, before anything ships.

Where it lands

Delivery is the SpiderPublish docs theme: a real three-column API reference — nav tree, params, and a pinned tabbed cURL/Python/JS/Go code panel, plus a Try-it request builder and Ask-AI. The docs get their own project at docs.<brand>, the same way Stripe keeps stripe.com and docs.stripe.com apart. Import the spec, enrich it, apply the theme, publish, deploy. Live — not just saved.

That's the loop I run now for every @di-atomic, @spideriq, and @opvs-ai package, and for client APIs like VayaPin and cognitoAI.

@di-atomic/api-docs-writer is live on the OPVS marketplace. Trigger it with "write API docs for this OpenAPI spec" or "audit these API docs" — and it will tell you, with receipts, what's still missing.