Requirements
- Target platform
- OpenClaw
- Install method
- Manual import
- Extraction
- Extract archive
- Prerequisites
- OpenClaw
- Primary doc
- SKILL.md
Technical documentation patterns, structure, maintenance, and avoiding common documentation failures.
Technical documentation patterns, structure, maintenance, and avoiding common documentation failures.
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
README: what it is, how to install, quick example โ 5 minutes to first success Getting Started: guided tutorial for beginners โ one complete workflow Guides: task-oriented ("How to X") โ goal-focused, not feature-focused Reference: exhaustive API/CLI docs โ complete but not for learning Troubleshooting: common errors with solutions โ search-optimized
One-sentence description โ what problem it solves Installation โ copy-paste command that works Quick start โ minimal example that actually runs Link to full docs โ don't cram everything in README Missing any of these = users bounce before trying.
Every example must be tested โ untested examples rot within months Show complete runnable code, not fragments โ users copy-paste Include expected output โ confirms they did it right Bad: client.query(...) / Good: full script with imports, setup, and output Version-pin examples: npm install package@2.1.0 not npm install package
Every endpoint needs: method, path, parameters, request body, response, error codes Show real request/response bodies โ not just schemas Include authentication in every example โ most common missing piece Document rate limits and pagination upfront โ not buried in footnotes Error responses need as much detail as success responses
Screenshots โ UI changes, screenshots don't Version numbers โ hardcoded versions become wrong Links โ external sites move, break constantly "Current" anything โ write timelessly or add review dates Feature flags and experimental warnings โ often forgotten after GA
Docs live next to code โ same repo, same PR. Separate repos drift CI checks for broken links โ markdown-link-check or equivalent Runnable examples as tests โ if example breaks, build fails Review date in docs: "Last verified: 2024-01" โ signals freshness Delete aggressively โ outdated docs worse than no docs
Documenting implementation, not usage โ users don't care how it works internally Assuming context โ define acronyms, link prerequisites Wall of text โ use headings, bullets, code blocks liberally "See X for more info" without link โ friction kills follow-through Changelog as documentation โ changes โ how to use current version
Imperative mood: "Run the command" not "You can run the command" Second person: "you" not "the user" Present tense: "This returns X" not "This will return X" Short sentences โ one idea per sentence Active voice: "The function returns X" not "X is returned by the function"
Use words users search for โ not internal jargon Error messages verbatim in troubleshooting โ users paste exact errors Multiple ways to describe same thing โ alias common variations H2/H3 headings are SEO โ match user queries Avoid clever titles โ "Getting Started" beats "Your Journey Begins"
Major versions need separate docs โ v1 users shouldn't see v2 docs Migration guides between versions โ step-by-step, not just changelog Default to latest stable, link to older versions Mark deprecated features clearly โ don't just remove URL structure: /docs/v2/ not query params
Badge spam โ 15 badges before content Massive feature lists โ save for marketing page No installation instructions โ assuming everyone knows Screenshots without context โ what am I looking at? License-only README โ legal compliance โ documentation
Writing, remixing, publishing, visual generation, and marketing content production.
Largest current source with strong distribution and engagement signals.