.agents/skills/docs-creator/SKILL.md
North star: docs/solutions/style.md. Required reading. 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:
docs-plugin owns plugin-page execution only:
Plugin pages: load both. docs-creator first, docs-plugin second.
Before writing, read only what actually grounds the page:
docs/solutions/style.md — non-negotiablecontent/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.
Write the way style.md writes. 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:
Feature pages. Pair with docs-plugin.
Required shape:
Voice moves:
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 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.