| name | plugin-docs-authoring |
| description | Rules for writing and updating plugin documentation. Use when creating new docs pages, updating existing docs (README, docs/*.md), or reviewing documentation changes. |
Prerequisites
Read AGENTS.md first for terminology, architecture, and template types.
This skill only covers documentation-specific rules.
File Responsibilities
Each file has a strict scope. Do not mix responsibilities between files.
| File | Scope | Tone |
|---|
README.md | High-level overview, install, basic setup, links to docs | Short, navigational |
docs/configuration.md | Plugin options only | Technical, example-driven |
docs/admin.md | Admin panel user guide — what you can do, typical workflow | User-facing, no endpoints |
Writing Rules
Structure
- Start every page with a one-sentence summary of what the page covers.
- Use
## for main sections, ### for subsections. Do not go deeper than ####.
- Put "what the user can do" before technical details.
- End pages with a
## See Also section linking to related docs.
Style
- Write in English.
- Use short sentences and short paragraphs.
- Prefer bullet lists over long prose.
- Use code blocks for every example — never inline large snippets.
- Do not use emojis.
Cross-referencing
- Do not duplicate content between files — link to the authoritative page.
- If you remove a page, update all references across docs and README.
- Keep all internal links relative (
./blocks.md, ../blocks.md).
Checklist (run before finishing)
Workflow
When asked to update or create docs:
- Read this skill first.
- Identify which files are affected (use the File Responsibilities table).
- Read the current state of those files.
- Make changes following the rules above.
- Run the checklist.
- Report: list of changed files + short summary of what and why.
