A reusable OpenCode skill for writing structured, user-first technical documentation.
中文 · Install · Commands · IDE integration · FAQ
Most documentation problems are classification problems. A page that teaches a beginner, guides a working user, lists API fields, and explains design tradeoffs at once fails all four readers.
This skill makes an AI assistant decide what kind of document is needed before it writes anything, using the Diataxis compass:
| If the content… | …and serves the user's… | …then it belongs to… |
|---|---|---|
| informs action | acquisition of skill | a tutorial |
| informs action | application of skill | a how-to guide |
| informs cognition | application of skill | reference |
| informs cognition | acquisition of skill | explanation |
The skill then writes in that form, and says what to leave out. SKILL.md has the decision tree, the per-form anti-patterns, and the quality checks.
git clone https://github.com/88lin/diataxis-docs-skill.git \
~/.config/opencode/skills/diataxis-docsFor one project, run this from that project's root:
git clone https://github.com/88lin/diataxis-docs-skill.git \
.opencode/skills/diataxis-docsOpenCode has no skills.paths setting for arbitrary checkouts. With either supported location, the directory containing SKILL.md must be named diataxis-docs to match the skill's frontmatter name. Restart OpenCode afterwards.
Claude Code, verification steps, and troubleshooting are in Install the skill.
Ask in natural language:
Turn this messy guide into Diataxis-style docs.
Split this page into tutorial, how-to, reference, and explanation.
Design a Diataxis documentation system for my SDK.
Audit our docs site and flag pages that mix forms.
Or use a slash command for a specific mode:
| Command | Returns |
|---|---|
/docs-classify |
Which form a page belongs to, plus mixed-form signals |
/docs-split |
A split plan and a draft of each resulting page |
/docs-review |
Severity-tagged pre-publication findings |
/docs-audit |
Page-by-page classification of a docs directory |
/docs-quickstart |
A short path to first success |
Full output shapes: Slash commands.
The command files need a separate install step: OpenCode does not discover .opencode/commands/ nested inside a skill checkout. See Install the skill.
examples/messy-to-diataxis/ contains a realistic "Getting Started" page that does four jobs at once, and the four single-purpose pages it should become.
BEFORE before.md # 1 page, 4 jobs
AFTER after/01-tutorial.md # learn by doing
after/02-how-to.md # complete a task
after/03-reference.md # look up facts
after/04-explanation.md # understand why
| Page | For |
|---|---|
| Install the skill | Getting it loaded in OpenCode or Claude Code |
| Slash commands | What each command takes and returns |
| AI IDE integration | Exporting to Cursor, Copilot, Aider, and 8 more |
| Develop and contribute | Running the checks, adding evals and commands |
| Questions about scope and design | What it does not do, and why |
Reference material the skill loads on demand: blueprints per document type, a reader checklist, a template map to Good Docs Project templates, and Chinese-language anti-patterns.
SKILL.md is portable. The exporter writes it to the rule file 11 other assistants read, with the frontmatter each one needs:
python scripts/export_rules.py --list
python scripts/export_rules.py --target . --compactEight of the eleven default targets load into every request, so --compact matters. The optional legacy Cursor target is excluded by default. See AI IDE integration.
- Reader first. Write for what the reader is trying to do right now.
- One need per page. Do not mix learning, working, lookup, and reflection.
- Link, do not overload. Companion documents beat a longer page.
- Structure follows purpose. Choose the document type before the headings.
- A guide, not a plan. Apply the compass where you are, one step at a time.
Issues and pull requests are welcome. Open an issue first for anything larger than a fix. Run python scripts/check_local.py before pushing — CI runs the same command.
See CONTRIBUTING.md and Develop and contribute.
Built on ideas from Diataxis and The Good Docs Project. This repository does not mirror either; it distills them into a skill.
MIT. See LICENSE.