docs-creator

# Docs Creator This skill is the source of truth for Plate docs style and workflow. Every rule below collapses to "docs that teach humans AND parse cleanly for agents." Most bad Plate docs fail the same way: reference dump instead of a working path, blurred ownership, missing "why", vibes instead of code. This skill kills that drift. ## Who owns what `docs-creator` owns shared docs law: - voice and tone - information order - lane selection - ownership clarity - anti-slop rules - agent affordances - plugin-page section order, kit/manual structure, component/API checks, and plugin-specific examples Plugin pages are a lane inside `docs-creator`, not a separate skill. ## Goal Template Use the docs goal template for non-trivial docs work: ```bash node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template docs \ --title "<short docs title>" ``` Use it when the task creates or rewrites a page, changes public behavior docs, touches plugin/API/spec/serialization docs, moves routes, changes examples, or could leave stale imports, links, previews, ownership claims, or API claims. When docs are only a supporting surface under another dominant task, do not switch the primary template to `docs`. Add the docs pack to the owning plan: ```bash node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template task \ --with docs \ --title "<short task title>" ``` For heavyweight architecture or proposal work that also changes docs, use the major primary template plus packs, for example: ```bash node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template major-task \ --with docs \ --title "<short major task title>" ``` Do not use it for tiny copy edits, typo fixes, or one-line link repairs unless the caller explicitly asks for a goal-backed docs task. `docs-creator` owns docs doctrine and routing. The docs goal template owns the closeout contract: lane classification, source-backed claims, ownership map, link/demo checks, content build, and anti-slop audit. ## Source Of Truth This file is the source. Generated skill copies are output. - Edit `.agents/rules/docs-creator.mdc`, not `.agents/skills/docs-creator/SKILL.md`. - After changing this rule, run `pnpm install` to regenerate the skill copy. - Verify the generated skill contains the intended rule text before handoff. - If generated output drifts, fix this source file and regenerate. Do not patch generated skill text by hand. ## Read First Before writing, read only what actually grounds the page: - the target doc - nearest sibling docs in the same lane - the source code for the behavior or API being documented - strongest baselines: - `content/docs/index.mdx` - `content/docs/installation.mdx` - `content/docs/installation/plate-ui.mdx` - `content/docs/(guides)/plugin-rules.mdx` - `content/docs/(guides)/plugin-input-rules.mdx` - `content/docs/(plugins)/(serializing)/html.mdx` - `content/docs/(plugins)/(serializing)/markdown.mdx` - `content/docs/(plugins)/(ai)/ai.mdx` - relevant `docs/solutions/*` learnings when the lane touches ownership, spec truth, docs drift, or authoring doctrine Start from code plus the best baseline doc. Not from old prose alone. When the task is a docs gap review, read sideways before writing: - the likely target lane - the nearest reference page - the nearest concept guide - the feature/plugin page, if one owns the behavior - the docs nav surface (`content/docs/meta.json`) when adding, moving, merging, or deleting pages The question is not "can this become a page?" The question is "which page shape will keep the concept findable without duplicating the reference?" When the work touches docs style, shadcn parity, registry components, install pages, or MDX component usage, also read the local shadcn reference corpus: - `../shadcn/apps/v4/content/docs/components/base/button.mdx` - `../shadcn/apps/v4/content/docs/components/base/chart.mdx` - `../shadcn/apps/v4/content/docs/components/base/sidebar.mdx` - `../shadcn/apps/v4/content/docs/installation/next.mdx` - `../shadcn/apps/v4/content/docs/registry/getting-started.mdx` - `../shadcn/apps/v4/mdx-components.tsx` - `docs/sync/shadcn/docs-style-corpus-2026-05-31.md` when present Use shadcn as the reference for density, MDX component grammar, and page scaffolding. Use Plate source as the authority for behavior, ownership, package names, and examples. ## Gap Review And Page Topology When asked whether docs have gaps, answer with a page-topology decision, not a pile of possible pages. Classify each gap: | Gap | Fix | | --- | --- | | Missing mental model across several APIs or packages | Add a guide/system concept page. | | Missing exact options, signatures, or return values | Improve the API/reference section. | | Missing setup path for one capability | Improve the plugin/feature page. | | Same concept split across two small pages | Merge into the stronger page and redirect links. | | A page only repeats an existing reference | Delete or shrink it into a link from the canonical page. | | A behavior is source-real but hard to discover | Add a concept guide plus cross-links from the owning references. | Strong default: **concept page over primitive pages** when a behavior is a pipeline. For example, do not create separate "Delete" and "Merge" pages when the reader needs the editing lifecycle. Create one "Editing Behavior" guide with delete and merge as headings, then link the rule/API references into it. Keep references as references: - `Plugin Rules` owns `plugin.rules` keys and actions. - API pages own exact signatures and tables. - Plugin pages own feature setup and feature-specific behavior. - Concept guides own the mental model that crosses those pages. When adding a concept page, update the adjacent references with one precise cross-link. Do not copy the same explanation into every page. ## Shadcn Style Layer The shadcn docs style is not "more words with friendlier tone." It is dense, structured, and component-driven: - Frontmatter owns the page title and description. The body starts fast. - Lead prose is usually one short paragraph. Copy that density unless Plate needs extra disambiguation. - One section does one job. Install, usage, examples, RTL, composition, and API reference are separate lanes. - MDX components carry structure. Use `<ComponentPreview>`, `<CodeTabs>`, `<Steps>`, `<ComponentSource>`, `<Callout>`, `<LinkedCard>`, and `<Tabs>` when they express real choices or workflow, not as decoration. - Package-manager commands stay as plain install/run fences so Plate can render package-manager command tabs. Reserve `<CodeTabs>` for CLI/manual choices. - Titled code fences are the default for file edits. Use `title="..."` and `showLineNumbers` when a path or line context matters. - Examples come as visible previews first, then terse explanation. Do not explain a visual variant for three paragraphs when the preview and one line do the job. - API reference is compact: exact prop/option tables and short caveats, not a tutorial restart. Plate docs can stay more explanatory where the editor runtime is genuinely harder than a UI component, but the default should be shadcn-dense: short lead, clear section shape, real MDX affordances, no filler. ## Voice This is where docs usually go wrong. - **Direct.** Use "you" when it helps, but do not pad every section with "we" or "let's". - **Shadcn-dense.** Short paragraphs, concrete verbs, visible examples, no essay before the first working path. - **Progressive.** One new idea per paragraph. Never land an advanced pattern before the fundamentals. - **Why before what.** Every non-obvious choice gets a one-line reason. - **Guide, don't just show.** One sentence of context before every code block. Code is never a substitute for prose. - **Build progressively.** Start with the simple path, then add complexity only after the reader has a working model. - **Celebrate completion.** End a section with a landing: "Done.", "That's it.", or one line on what the reader now has. - **Real code.** Never write placeholder comments (`// your logic here`). Write what the reader would actually write. - **Reinforce in tiers.** Concept in prose → example in code → recap in a table if it's an enum or option matrix. - **Highlight real gotchas.** Use callouts for environment constraints, security warnings, explicit-not-automatic behavior, or other points readers will actually hit. Shadcn-terse vs conversational: **the tension resolves cleanly.** Prose is conversational. Code blocks and API reference sections are shadcn-terse. Don't mix the two tones within a section. Banned openings: - "In this guide, we will explore..." - "This comprehensive guide..." - "This robust, powerful, seamless..." - Any marketing adjective pile before the reader sees the problem. ## Structural Rules ### Opening (above the first `##`) Three sentences max: 1. What the page is about and what it does for the reader. 2. If a sibling concept exists, one inline sentence distinguishing them. Plain prose — not a Callout. 3. One sentence on what the guide will walk through. Nothing else above the first `##`. No feature brag, no marketing adjectives, no TOC cosplay. ### Ownership - Always state where behavior lives: core runtime, feature package, kit, app-local copied code. - If the page says "the kit also adds X", the ownership boundary matters — surface it in a table or callout. - For every named API, the reader should be able to tell you which package/layer owns it within 10 seconds of scanning. - For behavior that spans packages, name each layer: input rule, plugin rule, transform, normalization, selection, UI component, registry kit, app-local copy. If a layer is not involved, do not imply it is. - Use an ownership table when prose would blur the boundary. ### Quick path first - The reader does the thing before hitting the appendix. - The kit-based path is the default quick path in this repo. - Manual/headless path comes after, labelled as such. - When there are multiple valid starts, use a small branch selector near the top: cards or links that jump to exact sections like "Use the CLI" and "Existing Project". - For CLI/manual install choices, prefer `<CodeTabs>` with `Command` and `Manual` tabs over stacked sections. - For package-manager variants, write the canonical install/run command in a plain code fence and let Plate's command renderer produce the package-manager tabs. ### Reference last - Exact helper signatures, option matrices, primitives → `## API Reference` at the end. - Don't sprinkle precise type signatures across tutorial sections. It kills flow. - API Reference = ProseMirror-style exactness. Tutorial = Slate-style narrative. ### Headings agents can find - Use stable, predictable heading names matching the real API or concept in code. - `### createMarkInputRule` beats "Creating a mark rule". - `## Kit Usage` / `## Manual Usage` / `## API Reference` are stable slugs across the repo. Don't invent synonyms. - Same lane → same heading names. Cross-page consistency matters for agent navigation. ### Page length - If the page passes ~300 lines, add an anchor list or "On this page" jump block near the top. - If the page passes ~600 lines, consider splitting. Ask first. ### Navigation And Routing Adding, moving, merging, or deleting a docs page is a routing change. - Add the MDX page in the lane folder that matches its route. - Update `content/docs/meta.json` root `pages` when the raw page tree order should change. - Update `_plate.categoryGroups` in `content/docs/meta.json` when the sidebar overlay should show nested grouping, labels, descriptions, or CN titles. - Update `_plate.items` when the route needs title, label, description, keywords, or CN title metadata. - Add links from the nearest owning pages, not from every vaguely related page. - If no `.cn.mdx` page is added, know that CN docs may fall back to English. Record that as a caveat rather than pretending the page is translated. - Verify the route itself, not just the source file. Pager order and sidebar grouping are rendered contracts. Do not leave orphan pages: every new page needs a route, a nav decision, and at least one useful inbound link from the owning neighborhood. ### Release Docs `/docs/releases` is docs topology, not changeset policy. - `/docs/releases` renders generated package release data and generated Plate UI changelog JSON. Do not hand-author release-page Plate UI entries; use the `registry-changelog` skill for source entries, generation, and verification. - Keep the latest two major release groups on `/docs/releases`. - Move older v49+ major groups to dedicated `/docs/releases/<major>` pages instead of burying them in a catch-all archive. - Link each older major page from `/docs/releases` under `Older releases`. - Link `v48 and earlier` from `Older releases` to `/docs/migration/v48`. - Changesets own package-release bullets. They do not own release-page retention, routing, or archive shape. ## Code Example Rules - Repo-backed examples only. If a kit does what you're teaching, cite the exact kit file. - Include real imports. Show `platejs` vs `platejs/react` vs `@platejs/*` paths explicitly. - Use `// ...otherPlugins,` only when the omission is obvious. - No placeholder comments (`// your logic here`, `// Your validation logic`). - `showLineNumbers` + `{n-m}` highlights on snippets longer than ~15 lines. - `title="filename.tsx"` when file context matters. Inline code hygiene: - CommonMark matches inline-code delimiters by backtick-run length. Literal `` ` ``` ` `` inline breaks rendering. - To show triple backticks, rephrase ("a triple-backtick fence") or use a fenced block. ## Links - Link the specific leaf page, not a broad hub. - Don't link the same target three times in one section. - If you're displacing an old page, **do not link back to it** — it reinforces the page you're killing. - Inline links on the exact concept being referenced. - When a page has a close sibling concept, link the sibling near the top. ## Demos and Previews - `<ComponentPreview name="..." />` only when the demo exists in the registry. - Never fake a demo name to balance a page. - If the demo lands after the doc, ship the doc without the preview and add it when real. ## Agent Affordances Agents specifically benefit from: - **Exact names in prose.** API names, file paths, package specifiers — spelled out, not paraphrased. - **Predictable heading slugs.** Same names for the same sections across similar pages. - **Real imports.** Import statements complete enough to copy-paste and run. - **No invented APIs.** If the source code does not ship it, it does not exist. - **Tables for enums and variants.** Bullet-buried enums get missed. - **Disambiguation on near-name siblings.** If `FooPlugin` and `FooClassicPlugin` coexist, the first sentence says which one this page is about. ## Anti-Slop Rules Do not: - Use changelog voice: "previously", "now supports", "has been removed", "new feature", "updated to". - Open with generic fluff or marketing adjectives ("comprehensive", "robust", "seamless", "powerful", "first-class"). - Brag in bullet lists before the reader can do anything. - Dump a full API catalog before the happy path. - Blur package-owned behavior with app-local copied code. - Flatten adjacent lanes because they smell related. - Hide critical environment limits halfway down the page. - Invent examples that skip required imports or dependent plugins. - Paste giant code walls without explaining why the code matters. - Duplicate whole doc blocks when a precise link would do. - Keep stale routes, file paths, imports, or package names in prose. - Write placeholder comments (`// your logic here`). - Claim a model or behavior the runtime does not implement. - End with a redundant "Summary" or "Recap" — the celebrate-completion line is enough. - Ship a `<ComponentPreview>` pointing at a demo that does not exist. - Reference a route you're about to delete or displace. Silence in the source code is a gap, not an agreement. ## Workflow 1. Classify the lane. 2. Lock the owner map. 3. Decide page topology: add, merge, delete, or cross-link. 4. Define the fastest success path. 5. Gather 1–3 real examples from code. 6. Write the quick path. 7. Add deeper explanation and boundaries. 8. Add API or reference material only where it earns its keep. 9. Wire navigation, neighbor links, and metadata. 10. Trim repetition, vague adjectives, and fake completeness. 11. Verify every claim against the current repo. ## Lane Map Use the page shape that matches the job, not the one you wrote last time. | Lane | Job | What readers need first | | --- | --- | --- | | Install / get-started | help someone adopt Plate | choose a path, install, next step | | Component / registry item | teach a copied UI component or registry item | preview, install, usage | | Guide / system | teach a runtime or concept | mental model, ownership, quick start | | Plugin / feature | teach one capability | what it does, quickest setup, manual path | | Serialization / conversion | explain import/export or round-trip | direction split, environment constraints | | Workflow / AI | explain multi-surface flows | setup path, runtime flow, optional UI | | API reference | explain an exact surface | short purpose, exact contract, caveats | | Spec / law / behavior | lock a contract | model, ownership, evidence, explicit gaps | ## Lane Templates ### Install / Get Started Entry docs like `content/docs/index.mdx`, `content/docs/installation.mdx`. Required shape: 1. Short opening: what Plate is or what the guide does. 2. If there are multiple starts, add a compact branch selector that links to exact sections. 3. Recommended path first. 4. Alternative paths after. 5. Next steps / where to go next. Voice moves: - Choose for the reader when there's an obvious best path. - "Let's start with the fastest setup" beats "Several setup options are available". - Keep branching shallow. - Link the exact next leaf, not a vague hub. - Use `<Steps>` with `###` step headings for actual procedures. - Show a working command, then the smallest real file edit that proves the install worked. ### Component / Registry Item Pages like Plate UI component docs or registry-item docs should follow the shadcn component shape unless Plate source proves a different ownership model. Required shape: 1. Frontmatter title and description. 2. Real `<ComponentPreview name="..." />` immediately after the frontmatter when the demo exists. 3. `## Installation` with `<CodeTabs>`: - `Command` tab for the CLI command - `Manual` tab with `<Steps>` only when manual install is realistic - `<ComponentSource>` for the source file being copied 4. `## Usage` with imports first, then the smallest working JSX.