| name | doc-writer |
| description | Write, review, and organize the human-authored prose around a generated API reference on an rspress-plugin-api-extractor site. Use when authoring or editing a guide, concept, example, or package-overview page; deciding a site's information architecture and sidebar mount (guides spine + overview + generated api tree); setting page frontmatter (title, one-sentence description); deciding whether a code snippet earns a with-api fence versus a plain fence; writing a migration note for a breaking API change; cross-linking prose into the generated reference; or running an editorial review of a docs site. Do NOT use for the mechanics inside a with-api fence — notation, @errors, ---cut---, why a block will not compile (see twoslash); for ApiExtractorPlugin configuration, routes, theming or model plumbing (see plugin-config); or for generic RSPress routing, _nav.json, components, or frontmatter fields beyond title/description (see rspress-core). |
doc-writer
Load this skill when you are writing or editing the human-authored documentation on a site built with rspress-plugin-api-extractor — the guides, overviews, concept and example pages a person writes by hand — or reviewing a site's prose for quality. It owns the editorial craft: what to write, how to structure it, and when a code snippet earns a live with-api fence.
It does not touch the generated reference tree (that is build output — see below) and it does not own code-fence mechanics.
Route these adjacent decisions elsewhere:
- The mechanics inside a
with-api fence — notation (^?, @errors, ---cut---), why a block fails to compile, what strips on copy — see twoslash. This skill decides whether a snippet gets with-api; twoslash handles it once you have.
ApiExtractorPlugin configuration — options, routes, --api-* theming, model plumbing — see plugin-config.- Generic RSPress mechanics —
_nav.json, sidebar field semantics, built-in components, frontmatter fields beyond title/description — see rspress-core.
Boundary: looks similar, is not
This skill and twoslash both concern code examples, so they read as one job. They are not.
- doc-writer owns the editorial when: does this snippet deserve to be a live, type-checked
with-api block at all? That is a judgment about honesty and audience, made before any fence exists.
- twoslash owns the how: given that a block is
with-api, what notation goes in it, why it compiles or fails, what the reader copies.
Decide with this skill; author with twoslash. A snippet that should stay a plain illustrative fence never reaches twoslash at all.
Site information architecture
A site built with this plugin has three tiers. Keep them distinct; readers navigate down through them.
- A guide spine — hand-written pages that teach the package by task (getting started, then one page per real workflow). This is where a reader lands and learns.
- A per-package overview — one page that frames the package: what it is, why it exists, install, a quick start, and the topic sections that link into the guides and reference. On a portal, one overview per package.
- The generated reference — the plugin-owned
api/ tree, one page per API item. You link into it; you never author inside it.
Mount the three tiers in the site's root _meta.json (array form — see rspress-core) with one entry each:
[
{ "type": "file", "name": "index", "label": "Home" },
{ "type": "dir", "name": "guides", "label": "Guides", "collapsible": true, "collapsed": false },
{ "type": "dir", "name": "api", "label": "API Reference", "collapsible": true, "collapsed": true }
]
The api dir entry is the only place you touch the generated tree — it mounts the plugin's output into the sidebar. Everything under it is build output.
The generated tree is read-only
The plugin rewrites changed pages under api/ and deletes stale ones on every build, so any hand-edit there is silently reverted. The API prose comes from the documented package's TSDoc. When the reference is wrong, the fix is upstream — the source comment and a model rebuild — reported as a finding, never patched in the generated MDX. Your editorial work lives entirely in tiers 1 and 2.
Frontmatter convention
Every hand-written page carries two frontmatter fields and, usually, no more:
title — the page's short title (also the sidebar/tab label).description — one sentence, written to stand alone as an Open Graph / search snippet. Say what the page gives the reader, in a full sentence, not a keyword list.
---
title: Getting started
description: Create a pipeline, run it, and inspect its status — the core kitchensink workflow end to end.
---
Fields beyond these two (layout, hero, pageType) are generic RSPress frontmatter — see rspress-core.
The with-api discipline rule
This is the editorial call this skill exists to make.
- Real, importable code gets
with-api. If a snippet imports from the documented package and a reader could run it, mark the fence with-api so it is type-checked against the real API model and stays honest as the package changes. This is the default for any example built from the package's public surface.
- Shape sketches stay plain fences. Pseudo-code, a JSON/config fragment, a partial signature written to illustrate a shape, or a snippet that references symbols the package does not export — none of these should compile, so none should be
with-api. A plain ```ts fence is correct; forcing with-api onto them produces noise errors that erode trust in the ones that matter.
The test is one question: should this compile against the real package? Yes → with-api (then hand off to twoslash). No → plain fence. Never reach for with-api to make a non-program "look rigorous"; a red squiggle on a snippet that was never meant to run is worse than a plain fence.
Trap: ```typescript twoslash vfs is dead pre-1.0 syntax. If you find it while editing or reviewing an existing page, it is a broken block silently no longer type-checking — replace the meta with with-api. The mechanics belong to twoslash; flagging it is editorial.
The API-reference handoff
A guide or overview teaches a slice; the generated reference is the authority for everything. Close hand-written pages by handing the reader off to it, so prose and reference stay in their lanes:
- End a guide with a "Next steps" / "Learn more" list that includes an absolute link into the reference (
[API reference](/my-library/api)).
- When prose names a type it does not fully document, link that mention to its generated page rather than re-documenting it inline.
This keeps guides short and lets the reference carry exhaustive detail — the two never compete to be the source of truth. Link construction and the hub-table pattern are in references/cross-linking.md.
Common mistakes
- Hand-editing a generated
api/ page. It is reverted on the next build; the fix is the source TSDoc plus a model rebuild, raised as a finding.
- Forcing
with-api onto a shape sketch. A snippet that was never meant to compile earns a red squiggle that trains readers to distrust the examples that are real. Plain fence.
- Leaving a
twoslash vfs block in an edited page. Dead syntax — it silently stopped type-checking. Convert to with-api.
- Re-documenting a type inline instead of linking to its reference page. Prose drifts from the model; link the mention and let the generated page be authoritative.
- A guide with no handoff. A reader who finishes the prose should be pointed at the reference, not left at a dead end.
- A
description that is a keyword list, not a sentence. It ships as the OG/search snippet; write it to read as one standalone sentence.
- Orphaned pages. A page not reachable from
_meta.json or a hub link is invisible; every hand-written page needs a route in.
Reference map
Load on demand; none is required to write a first page. Each answers a narrower question than this file.
references/page-skeletons.md — the Concept / Guide / Example page structures with content-source mapping, and the package-overview template.references/review-rubric.md — the editorial-review severity ladder (Critical → Low) and the pass checklist.references/sync-workflow.md — the "the API changed, update the prose" flow grounded on the plugin's snapshot statuses, with the migration-note pattern.references/cross-linking.md — absolute route links, hub tables, guide↔reference bridges, and the known-issues genre (status-stamped error signatures).
