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:

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:

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:

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:

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 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.
5. ## Examples with one visible variant per ### section.
6. Optional ## RTL, ## Composition, or other behavior sections when the source/demo actually supports them.
7. ## API Reference last with compact prop/option tables.

Voice moves:

• Preview before explanation when the component is visual.
• One sentence before each variant preview is enough.
• Use exact registry names and file paths.
• Do not add <PackageInfo> to UI component pages unless the package itself is the thing being taught.
• Do not fake a manual path. If the CLI is the only supported path, say that.

Guide / System

Pages like plugin-rules.mdx, plugin-input-rules.mdx.

Required shape:

1. Opening (3 sentences max, per Structural Rules).
2. Immediate inline disambiguation if a sibling concept exists.
3. Ownership model.
4. Quick start.
5. Deeper mechanics.
6. API reference last.

Voice moves:

• Open with what the system is and what it is not.
• Ownership table early, not buried in prose.
• Happy path before the full primitive catalog.
• If something is explicit, say "explicit" — never imply hidden defaults.
• End each mechanics section with a one-line landing.
• If the guide explains a pipeline, use predictable section names for each stage. Example: Runtime Pipeline, Break Behavior, Delete Behavior, Merge Behavior, Normalize Behavior, Selection Behavior, Recipes, API Reference.
• Keep the concept guide above the details but below the reference. It should make reference pages easier to use, not replace them.

Behavior / Runtime Concept

Pages like editing-behavior.mdx.

Use this lane when behavior crosses multiple source files, plugins, or docs lanes. The reader needs the lifecycle, not a dump of every option.

Required shape:

1. Opening with sibling disambiguation. Example: "Use Plugin Rules for declarative node policy; use Editor Methods for imperative transforms."
2. ## Choose the Right Surface or equivalent decision table.
3. ## Runtime Pipeline with owner map.
4. One section per pipeline stage.
5. ## Recipes for common outcomes.
6. ## API Reference linking to the canonical references.

Source audit:

• Read the public reference docs.
• Read the core dispatcher or override layer.
• Read the transform implementation that actually mutates the document.
• Read feature-package defaults for examples.
• Read UI/registry code only when the behavior is UI-owned.

Voice moves:

• Say which stage owns the behavior.
• Keep primitive APIs in reference links, not repeated in prose.
• Use tables for decision paths and stage behavior.
• If two terms sound similar, split them early. Example: document-level merge rules are not table cell merge commands.
• End with what the reader can now decide or configure.

Plugin / Feature

Plugin and feature pages are headless first. The package/plugin owns the feature; Plate UI components are render examples unless the source proves they own behavior.

Required shape:

1. Short opening or a real <ComponentPreview name="..." /> if the demo exists.
2. <PackageInfo> with features derived from source, not marketing bullets.
3. ## Kit Usage when a kit exists:
   • wrap procedural setup in <Steps>
   • use ### Installation and ### Add Kit
   • include <ComponentSource name="actual-kit-name" />
   • list relevant kit components from apps/www/src/registry/registry-kits.ts
   • show createPlateEditor({ plugins: [...RelevantKit] })
4. ## Manual Usage:
   • show the package install command
   • import plugin APIs from the actual platejs or @platejs/* path
   • add the plugin to createPlateEditor
   • use .withComponent() when only assigning a component
   • use .configure() when options, shortcuts, injection, or extra behavior are part of the example
5. Style plugins without distinct components should emphasize inject.nodeProps, defaults, and inject.targetPlugins.
6. Toolbar sections only when the toolbar affordance exists. Check kit dependencies before writing about *ToolbarButton, Turn Into, or Insert controls.
7. ## Plugins for actual plugin objects.
8. ## API Reference and ## Transforms only for real editor.api.<plugin>.* and editor.tf.<plugin>.* surfaces.

Voice moves:

• Kit path is the quick path. Say so.
• Keep the headless package contract explicit even when the fast path uses UI.
• Components are render examples, not the feature itself.
• Never document plugin APIs or transforms the source does not actually ship.
• Preserve existing <APIOptions>, <APIParameters>, and <APIReturns> formatting when editing a working page.
• Use content/(plugins)/(functionality)/dnd.mdx as the primary plugin-page structure baseline when the target page has no better sibling.

Serialization / Conversion

Pages like html.mdx, markdown.mdx.

Required shape:

1. Explain the two directions up front (A→B and B→A).
2. Split the page by direction.
3. State environment constraints (server vs client, static vs React) before the first example.
4. Show extension points only after the base path is clear.
5. Put the heavy API reference late.

Voice moves:

• "A to B" and "B to A" never share a section.
• Call out server/client/static/React-only boundaries early — in a Callout if required.
• Use correct imports for each environment.
• If round-trip behavior has limits, say so where the user will hit them.

Workflow / AI

Pages like ai.mdx.

Required shape:

1. What the feature enables (one paragraph).
2. Fastest setup path.
3. Runtime architecture or flow.
4. Client vs server split.
5. Optional UI surfaces.
6. Utilities and API reference.

Voice moves:

• Separate required runtime pieces from optional UI sugar. Explicitly.
• Multi-surface flows stay explicit: editor, route, provider, streaming, transforms.
• If the page is passing ~300 lines, add an on-page jump list near the top.
• Don't dump every helper until the main workflow is already clear.

API Reference

When the page is mostly contract, not onboarding.

Required shape:

1. Short purpose paragraph.
2. Surface grouping.
3. Exact parameters, options, returns.
4. Caveats and constraints.

Voice moves:

• No tutorial cosplay. Shadcn-terse.
• Still one sentence on when to use the API.
• Use <API> blocks or a consistent table format.
• Examples minimal and exact.

Spec / Law / Behavior

Behavior-spec, law, protocol docs.

Required shape:

1. Goal or contract.
2. Explicit owner map.
3. Model before UX chrome.
4. Evidence or source backing.
5. Clear gap markers where evidence is missing.
6. Reference appendix only after the contract is clear.

Voice moves:

• Lock the node model and affinity before writing hover, toolbar, or interaction chrome.
• Treat silence in references as a gap, not an agreement.
• Prefer binary wording over vibes.
• If the docs claim behavior the runtime does not implement, the docs are wrong until the code changes.

This lane is stricter than a normal concept guide. Use it when the doc becomes the contract for future implementation or review. Use Behavior / Runtime Concept when the runtime already exists and the reader needs to understand it.

Writing Voice Examples

Opening — bad:

This guide provides a comprehensive overview of input rules. Input rules are a powerful feature of Plate that enable users to define custom syntax transformations.

Opening — good:

Plugin Input Rules are Plate's runtime for typed editor conversions. As you type, paste, or press Enter, the first matching rule transforms the editor on the spot — # becomes a heading, **bold** turns on bold, a pasted URL becomes a link.

Config example — bad:

Here is an example of configuring the plugin:

Plugin.configure({ /* options */ });

Config example — good:

Reach for .configure() when you need more than the default behavior. Let's add a keyboard shortcut:

Plugin.configure({ shortcuts: { toggle: 'mod+alt+s' } });

Changelog drift — bad:

The API has been updated. Previously, options were passed as strings; now they support objects.

Changelog drift — good:

Options are passed as objects. Example: { variant: 'paste' }.

Completion — bad:

This concludes the overview. You have now been presented with the available options for configuring input rules.

Completion — good:

Done. You now have a working markdown shortcut — type # and watch the heading land.

Structure & Formatting

• <Steps> for real multi-step procedures.
• ### inside <Steps> for sub-steps.
• <CodeTabs> for CLI/manual choices only.
• Plain install/run command fences for package-manager variants.
• <ComponentPreview> near the top of component pages when the preview exists.
• <ComponentSource> when the page asks the reader to copy a registry file.
• <LinkedCard> or compact cards for branch selection, not for decoration.
• Code blocks with title="..." when file context matters.
• showLineNumbers + {n-m} line highlights when a large snippet needs focus.
• Tables for option matrices, ownership boundaries, or variant comparisons.
• Callouts for:
  • environment constraints
  • security warnings
  • "this is explicit, not automatic" guidance

Do not force <ComponentPreview>, <PackageInfo>, or a giant feature list just because another page had one. Every section earns its place.

Verification Checklist

Before finishing a docs change:

• pnpm --filter www build:source parses the MDX cleanly.
• pnpm --filter www check:docs passes when docs source parity or generated source can be affected.
• Every named API, option, transform, and component exists in the source.
• Every import path matches the current repo/package layout.
• Every ownership claim matches the code.
• Every link target or route is real and not about to be removed.
• Every <ComponentPreview> name points at a demo that exists.
• content/docs/meta.json parses when docs nav metadata changes.
• A local route check proves new or moved pages render. Curl is enough for text-only pages; use Browser proof for visual/component behavior.
• Opening lands in 3 sentences or fewer.
• A first-time reader could complete the happy path before reaching ## API Reference.
• No placeholder comments, no TODO, no dead anchors.
• No changelog voice ("previously", "now supports", "has been removed").
• Neighboring lanes are split cleanly enough that a reader can answer "where does this behavior live?".
• If .agents/rules/docs-creator.mdc changed, pnpm install regenerated the skill copy and the generated SKILL.md reflects the source.

If the page still reads like stitched-together notes, it is not done.