.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/rules/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/rules/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/rules/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.
Before writing, read only what actually grounds the page:
content/index.mdxcontent/installation.mdxcontent/installation/plate-ui.mdxcontent/(guides)/plugin-rules.mdxcontent/(guides)/plugin-input-rules.mdxcontent/(plugins)/(serializing)/html.mdxcontent/(plugins)/(serializing)/markdown.mdxcontent/(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.
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.
## 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.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 |
| 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/index.mdx, content/installation.mdx.
Required shape:
Voice moves:
Pages like plugin-rules.mdx, plugin-input-rules.mdx.
Required shape:
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:
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.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:contentlayer parses the MDX cleanly.<ComponentPreview> name points at a demo that exists.## API Reference.TODO, no dead anchors.If the page still reads like stitched-together notes, it is not done.