.agents/skills/docs-creator/SKILL.md
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.
docs-creator owns shared docs law:
Plugin pages are a lane inside docs-creator, not a separate skill.
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.
This file is the source. Generated skill copies are output.
.agents/rules/docs-creator.mdc, not .agents/skills/docs-creator/SKILL.md.pnpm install to regenerate the skill copy.Before writing, read only what actually grounds the page:
content/docs/index.mdxcontent/docs/installation.mdxcontent/docs/installation/plate-ui.mdxcontent/docs/(guides)/plugin-rules.mdxcontent/docs/(guides)/plugin-input-rules.mdxcontent/docs/(plugins)/(serializing)/html.mdxcontent/docs/(plugins)/(serializing)/markdown.mdxcontent/docs/(plugins)/(ai)/ai.mdxdocs/solutions/* learnings when the lane touches ownership, spec
truth, docs drift, or authoring doctrineStart from code plus the best baseline doc. Not from old prose alone.
When the task is a docs gap review, read sideways before writing:
content/docs/meta.json) when adding, moving, merging,
or deleting pagesThe 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.tsxdocs/sync/shadcn/docs-style-corpus-2026-05-31.md when presentUse 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.
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.When adding a concept page, update the adjacent references with one precise cross-link. Do not copy the same explanation into every page.
The shadcn docs style is not "more words with friendlier tone." It is dense, structured, and component-driven:
<ComponentPreview>, <CodeTabs>,
<Steps>, <ComponentSource>, <Callout>, <LinkedCard>, and <Tabs> when
they express real choices or workflow, not as decoration.<CodeTabs> for CLI/manual choices.title="..." and
showLineNumbers when a path or line context matters.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.
This is where docs usually go wrong.
// your logic here). Write what the reader would actually write.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:
##)Three sentences max:
Nothing else above the first ##. No feature brag, no marketing adjectives, no TOC cosplay.
<CodeTabs> with Command and
Manual tabs over stacked sections.## API Reference at the end.### createMarkInputRule beats "Creating a mark rule".## Kit Usage / ## Manual Usage / ## API Reference are stable slugs across the repo. Don't invent synonyms.Adding, moving, merging, or deleting a docs page is a routing change.
content/docs/meta.json root pages when the raw page tree order
should change._plate.categoryGroups in content/docs/meta.json when the sidebar
overlay should show nested grouping, labels, descriptions, or CN titles._plate.items when the route needs title, label, description,
keywords, or CN title metadata..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.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.
/docs/releases is docs topology, not changeset policy.
/docs/releases./docs/releases/<major> pages
instead of burying them in a catch-all archive./docs/releases under Older releases.v48 and earlier from Older releases to /docs/migration/v48.platejs vs platejs/react vs @platejs/* paths explicitly.// ...otherPlugins, only when the omission is obvious.// 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:
` ``` ` inline breaks rendering.<ComponentPreview name="..." /> only when the demo exists in the registry.Agents specifically benefit from:
FooPlugin and FooClassicPlugin coexist, the first sentence says which one this page is about.Do not:
// your logic here).<ComponentPreview> pointing at a demo that does not exist.Silence in the source code is a gap, not an agreement.
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 |
Entry docs like content/docs/index.mdx, content/docs/installation.mdx.
Required shape:
Voice moves:
<Steps> with ### step headings for actual procedures.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:
<ComponentPreview name="..." /> immediately after the frontmatter when
the demo exists.## Installation with <CodeTabs>:
Command tab for the CLI commandManual tab with <Steps> only when manual install is realistic<ComponentSource> for the source file being copied## Usage with imports first, then the smallest working JSX.## Examples with one visible variant per ### section.## RTL, ## Composition, or other behavior sections when the
source/demo actually supports them.## API Reference last with compact prop/option tables.Voice moves:
<PackageInfo> to UI component pages unless the package itself is
the thing being taught.Pages like plugin-rules.mdx, plugin-input-rules.mdx.
Required shape:
Voice moves:
Runtime Pipeline, Break Behavior, Delete Behavior,
Merge Behavior, Normalize Behavior, Selection Behavior, Recipes,
API Reference.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:
## Choose the Right Surface or equivalent decision table.## Runtime Pipeline with owner map.## Recipes for common outcomes.## API Reference linking to the canonical references.Source audit:
Voice moves:
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:
<ComponentPreview name="..." /> if the demo exists.<PackageInfo> with features derived from source, not marketing bullets.## Kit Usage when a kit exists:
<Steps>### Installation and ### Add Kit<ComponentSource name="actual-kit-name" />apps/www/src/registry/registry-kits.tscreatePlateEditor({ plugins: [...RelevantKit] })## Manual Usage:
platejs or @platejs/* pathcreatePlateEditor.withComponent() when only assigning a component.configure() when options, shortcuts, injection, or extra behavior
are part of the exampleinject.nodeProps, defaults, and inject.targetPlugins.*ToolbarButton, Turn Into, or Insert
controls.## Plugins for actual plugin objects.## API Reference and ## Transforms only for real
editor.api.<plugin>.* and editor.tf.<plugin>.* surfaces.Voice moves:
<APIOptions>, <APIParameters>, and <APIReturns>
formatting when editing a working page.content/(plugins)/(functionality)/dnd.mdx as the primary plugin-page
structure baseline when the target page has no better sibling.Pages like html.mdx, markdown.mdx.
Required shape:
Voice moves:
Pages like ai.mdx.
Required shape:
Voice moves:
When the page is mostly contract, not onboarding.
Required shape:
Voice moves:
<API> blocks or a consistent table format.Behavior-spec, law, protocol docs.
Required shape:
Voice moves:
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.
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:
tsxPlugin.configure({ /* options */ });
Config example — good:
Reach for
.configure()when you need more than the default behavior. Let's add a keyboard shortcut:tsxPlugin.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.
<Steps> for real multi-step procedures.### inside <Steps> for sub-steps.<CodeTabs> for CLI/manual choices only.<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.title="..." when file context matters.showLineNumbers + {n-m} line highlights when a large snippet needs focus.Do not force <ComponentPreview>, <PackageInfo>, or a giant feature list just because another page had one. Every section earns its place.
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.<ComponentPreview> name points at a demo that exists.content/docs/meta.json parses when docs nav metadata changes.## API Reference.TODO, no dead anchors..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.