Stats
Actions
Tags
From skills
Use when writing onboarding documentation for a software library, framework, or developer tool — tutorials, conceptual guides, getting-started flows, and the surrounding learning surface. Specifically tuned for taking a developer from zero to productive familiarity, and for content that pairs prose with embedded interactive code examples (REPLs, sandboxes, live previews). Covers information architecture, concrete page templates, writing voice, example patterns, and how to integrate interactivity. Distilled from analysis of 21 highly-praised OSS docs sites (Svelte, Vue, React, Rust Book, FastAPI, Django, MDN, Tailwind, Astro, Next.js, Stripe-shaped Supabase, etc.).
How this skill is triggered — by the user, by Claude, or both
Slash command
/skills:docsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill encodes patterns from 21 OSS doc sites that developers consistently single out as best-in-class for onboarding (not just popularity — *praise specifically for documentation*). Use it when you're writing material that has to take a reader from "what is this" to "I can build with it."
This skill encodes patterns from 21 OSS doc sites that developers consistently single out as best-in-class for onboarding (not just popularity — praise specifically for documentation). Use it when you're writing material that has to take a reader from "what is this" to "I can build with it."
The goal of onboarding docs is familiarity, not completeness. A reader who closes the page should be able to write something real and recognize the shape of the rest of the API. Reference docs serve a different purpose; they're covered here only at the boundary.
Use it for:
Don't use it for:
references/page-templates.md and stop there)If the user asks for "documentation" without specifying, ask: tutorial, conceptual guide, or reference? The page templates differ.
The reader is intelligent and impatient. They don't need to be sold. They don't need filler. They need to know what the thing is, why it's worth their time, and how to do something useful — fast. Praise consistently goes to docs that respect both halves: not condescending, not dense.
Code-and-prose ratio is the master variable. Every snippet should have just enough prose to explain why it exists and what changed from the previous one. Walls of code without prose teach nothing; walls of prose without code teach nothing. Aim for 1–4 short paragraphs around each substantive snippet.
State your scope. Praised docs explicitly say what they are and aren't (TypeScript Handbook lists non-goals; Django scopes the polls app upfront; React lists "You will learn" at the top of every page). Hidden scope is the #1 cause of reader frustration.
Work through these in order before writing anything. Answer them out loud (in your reply, briefly) so the user can correct course.
| Scope | Approach |
|---|---|
| Single page (one tutorial, one concept) | Pick one of the page templates below. Skip IA decisions. |
| 3–10 pages (a small tutorial series or guide bundle) | Use the Two-track lite IA. One sequential tutorial, plus a few concept pages. |
| 10+ pages (a real onboarding surface) | Use Diátaxis-influenced IA (Tutorial / Concepts / Reference / How-to). Decide the IA before writing pages. |
Three personas shape every other decision:
You're often writing for two of three. Decide which two and which is primary; design the entry point around the primary, but provide an obvious branch for the others. (TypeScript's intro routes by background; Vue's "Pick your learning path" does the same; Prisma's "two doors" routes by situation.)
This shapes example design more than any other factor.
| Available | Implications |
|---|---|
| In-page REPL/sandbox (Svelte tutorial, React docs, TanStack Query StackBlitz) | Examples can be runnable. Prose can say "click run", "modify line 3". Cumulative state across pages becomes possible. |
| Linked external playground (Vue, Solid, Rust Playground) | Snippets are static in the docs, but every substantive one ends with "Try it in the Playground →". |
| Live-rendered output (Tailwind) | Visual examples can render inline as actual styled HTML. The doc is the demo. |
| No interactivity, local-install only (Astro, Next.js, Django, FastAPI) | The reader runs the app locally. The doc must give exact terminal output, exact URLs to visit, exact files to create. Be explicit about every command. |
Auto-generated docs from running app (FastAPI's /docs) | The product's own UI is the playground. Onboarding can lean heavily on "now run it and play with the generated UI." |
State which environment your reader is in within the first 100 words of any tutorial. Don't make them guess.
| Surface | IA implication |
|---|---|
| Tiny (Zod-shaped, Hono-shaped, ~10–30 public symbols) | Skip the tutorial/reference split. A single long page or short guide-only set works. Zod's whole API is one scrollable page. |
| Medium (most libraries, ~50–200 symbols) | Standard split: tutorial → concept guides → grouped reference. |
| Massive (frameworks, runtimes) | Diátaxis tiers, with reference further sub-grouped by package/module. Tutorials carry one canonical project across many chapters. |
Pick one of these shapes deliberately. Don't drift.
One artifact, top-to-bottom, sequential. Reference lives elsewhere as a separate destination.
Use when: the material has a strong narrative spine and the reader will benefit from reading top-to-bottom (a language tutorial, a framework's mental-model intro, a long-form course).
Don't use when: readers will land on individual pages from search and need self-contained context.
Two top-level sections. Learn is sequential, narrative, one-canonical-example-grows. Reference is structural, alphabetical-by-symbol, examples-on-demand.
Use when: library is medium-sized and you have both new readers and returning lookups.
Cross-link rules:
This is the dominant pattern. Vue, React, Svelte, Solid, Next.js all use it.
Four explicit tiers, named on the landing page:
Use when: the library is large and the reader population is heterogeneous (beginners + production users + integrators all need different things).
Watch out for: the Tutorial/How-to boundary is the hardest. Tutorials teach concepts via building something; How-tos assume you know the concepts and just need to do a thing. If a page is both, split it.
The landing page presents two prominent CTAs that segment readers by their situation, not their skill level. Examples: "Use Prisma Postgres" vs "Bring your own database"; "Deploy a template" vs "Deploy with Wrangler CLI"; "I have an existing project" vs "Start from scratch."
Use when: there are two genuinely different starting situations that lead to different setup paths.
Don't fake it. Two doors that converge in three pages is just a fork; readers will resent it. Use only when the paths stay genuinely different for ≥5 pages.
Within whichever IA you pick:
Six templates cover most onboarding content. Use one, deliberately, per page. (Concrete copy-paste versions in references/page-templates.md.)
The single most important template. Used for sequential learning material.
H1: Chapter title (verb-led, concrete)
[Optional: chapter-number breadcrumb if part of a series]
"You will learn":
- Bullet 1 (concrete, capability-shaped)
- Bullet 2
- Bullet 3
[3–5 bullets max. Verbs, not nouns.]
[Continuity opener if part of a series:]
"In the previous chapter, you [X]. Now we'll [Y]."
[1–2 paragraph context: WHY this chapter, what problem it solves]
H2: First concrete step
[Prose that names the goal]
[Code]
[Prose that explains what changed and why]
[If interactive: "Try modifying X to see Y."]
H2: Next concrete step
[...same shape...]
H2: Pitfalls / Common mistakes [optional but recommended]
[Each pitfall is a short subsection or a Pitfall callout anchored to specific code]
H2: Recap
- Bullet 1 (what the reader can now do)
- Bullet 2
- Bullet 3
---
[Forward link]: "Continue to Chapter N+1 →" with one-sentence preview of what's next
Required elements: "You will learn" at the top, "Recap" at the bottom, forward link to next chapter, every code block introduced with prose and followed with prose.
Voice: second person, occasional collaborative "we"/"let's", anticipate the reader's likely confusion.
For explaining one idea at depth. Not part of a sequence.
H1: Concept name (noun)
[1-line definition — quotable, copyable, fits in a tweet]
[2–4 paragraph context: what problem this concept solves, where it fits, why it matters]
H2: A minimal example
[The smallest possible runnable code that shows the concept]
[Prose explaining what each part does]
H2: [First refinement — adds one orthogonal capability]
[Code]
[Prose]
H2: [Second refinement]
[Code]
[Prose]
H2: When to use it / When not to use it [optional but valuable]
H2: Pitfalls / Common mistakes
H2: See also
- Reference: [link to the API page]
- Related concepts: [links]
- Tutorial: [link to where this concept is first introduced]
Voice: more explanatory than tutorial pages. "Importance of X" framing (Solid) works well — explicitly argue why this matters before teaching it. Anticipate the "but why?" question.
For a 5-minute path from nothing to working code. Distinct from Tutorial chapter 1 — quickstarts have no narrative, just steps.
H1: Quickstart [or "Get started in 5 minutes"]
[1-paragraph opener: what you'll have at the end. Concrete. "By the end of this page, you'll have a Hono server returning JSON from a route."]
H2: Install
[Tabbed code block: npm / pnpm / yarn / bun, OR per-OS if relevant]
H2: Create your first [thing]
[Code, ~10–30 lines, complete and runnable]
[2–3 sentences naming the moving parts]
H2: Run it
[Single command]
[Expected terminal output, verbatim, in a styled block]
[The URL to visit]
H2: What just happened
[2–4 short paragraphs that name each piece of the example by file and line — gives the reader a vocabulary]
H2: Next steps
- → Tutorial (for the long version)
- → Concept guides (for understanding)
- → Examples (for patterns)
Required: a working app that runs in under 5 minutes of reader time, no detours, no "but first, let's understand X" — concept-teaching belongs in the tutorial.
For the page that explains why this library exists.
H1: Why [Project]?
[The Origins / The Problem]
[Narrative: what was the state of the world when this project started? What was painful?]
[How [Project] solves it]
[The core technical insight, plainly stated. One paragraph.]
[What this enables]
[2–4 capabilities, each with a one-sentence example or comparison]
[Where [Project] is heading]
[Brief, optional. Sets ongoing direction without making promises.]
[How it compares]
[Optional table or paragraphs. Honest about trade-offs.]
Voice: more narrative than other pages. Etymology/pronunciation of the name in the first sentence (Vite does this) humanizes the project. Avoid hype-superlatives; let the technical insight speak.
For the API surface. Even if you're focused on tutorials, you'll need these for cross-links.
H1: SymbolName
[1-sentence definition, plain English, no jargon if avoidable]
H2: Reference
H3: Signature / Syntax
[code: the type signature]
H3: Parameters
[list with types and one-line descriptions]
H3: Returns
[type and one-line description]
H3: Caveats / Exceptions [if any]
H2: Usage
H3: [Use case 1, named with a verb phrase]
[Code + 2–3 sentences]
H3: [Use case 2]
[Code + 2–3 sentences]
...
H2: Troubleshooting [React signature move — adopt it]
H3: [Common error or confusion 1]
[What's happening, what to do]
H3: [Common error 2]
H2: See also
- [Concept page that introduces this]
- [Related symbols]
Voice: drier than tutorial pages. Active, present tense. Short sentences. No personality — clarity is the personality.
For the cookbook of "how do I X" patterns. Used for tasks the reader already understands but needs the canonical pattern for.
H1: [Task, verb-led]
[2-sentence context: when you'd do this, what tradeoff to know]
[Code: complete, copy-pasteable, realistic]
[Optional: 2–3 sentence breakdown of the non-obvious lines]
[See also: related recipes]
Recipes should be browsable as a grid (titled, searchable). They're not a sequence — readers land on one from search.
The praised docs converge on a voice. It is not the only voice, but if you don't have a reason to deviate, default to this:
name field" beats "incorporate a designation."<Question: Question object (1)> isn't a helpful representation." pattern. When the reader is about to be confused, name the confusion in their voice and resolve it.Bad:
In order to facilitate the proper handling of asynchronous operations within your application, it is generally recommended that developers consider the utilization of the
awaitkeyword in conjunction with functions that have been marked asasync. This pattern, while initially perhaps somewhat unfamiliar, has become widely adopted across the JavaScript ecosystem.
Good:
Mark a function
asyncand you canawaitpromises inside it:async function getUser(id) { const res = await fetch(`/users/${id}`) return res.json() }
awaitpauses the function until the promise resolves. The function itself returns a promise — so callersawaitit too.
Same content. Half the words. The good version puts code at the center; the prose serves the code.
The single highest-leverage thing in onboarding docs is example craft. Get this right and the rest follows.
foo/bar. Not deliberately abstract.Cat model in a tutorial about ORMs is fine. A Cat extends Mammal cute hierarchy that's actually about teaching inheritance is not — the reader is now learning the cat metaphor instead of the language.Two ways to introduce a code block. Both work; pick consciously:
Default to problem-first in tutorials, code-first in references.
Output-as-comment (Zod, MDN). Append the result inline:
z.string().parse("hello")
// => "hello"
This makes examples self-explaining without extra prose.
Errors-first (Rust Book, TypeScript). Show the broken version, the actual compiler/runtime error verbatim, then the fix. Teaches the diagnostic path, not just the solution.
Listings with captions (Rust Book). Number significant code blocks: "Listing 2-3: Comparing the guess to the secret number". Lets prose refer back without scrolling: "as in Listing 2-3, we…"
File-path labels (Django, Vite, Bun, Next.js). Always label the file:
// src/routes/index.ts
export function GET() { ... }
The reader needs to know where to put the code.
Single canonical example refined across chapters (FastAPI's read_item). Don't introduce a new example every chapter. Take one example and refine it: add types, add validation, add error handling. The reader's mental model accumulates.
Single canonical app built across chapters (Django polls, Next.js dashboard, Astro blog). The whole tutorial builds one real artifact. Each chapter's code is the previous chapter's code plus one capability. Cumulative.
Recap, step by step (FastAPI). After showing 8 lines of code, re-present them as numbered single-concept items: "Step 1: Import FastAPI. Step 2: Create a FastAPI instance. ..." Each step gets one short paragraph. This is the strongest pattern for ensuring readers actually understood what they just saw.
// new).This is the user's specific need, so the rules go deeper here.
| Pattern | Examples | When to use |
|---|---|---|
| Two-pane tutorial (prose left, REPL right) | Svelte tutorial | Sequential learning where every step is a small modification to a running app. The strongest pattern for true zero-to-familiar. |
| Embedded sandbox per page | React, TanStack Query (StackBlitz) | Pages where you want one self-contained runnable demo per concept. Sandbox carries the example; prose narrates. |
| Live-rendered output | Tailwind | Visual concepts where the doc itself can render the result. Not a code editor — just live HTML. |
| Linked external playground | Vue, Solid, Rust | When embedding is technically hard. Every substantive example ends with a "Try it →" link. |
| Progressive sandbox state | Svelte tutorial (next exercise's starting code = previous exercise's solution) | Multi-page tutorials where you want the artifact to grow. The most demanding to author but the most rewarding to read. |
When the snippet is interactive, prose changes. Different rules from static-snippet prose:
Direct the reader's hand. "Click the Run button." "Change line 4 to use const." "Notice the type tooltip when you hover state." This is rare in static docs and feels strange to write at first. Do it anyway — interactive examples reward action, and readers don't always realize they can act.
Mark the modification clearly. If the reader is supposed to change something, say what to change and what to expect. "Change count + 1 to count + 2 and click Run. The number now jumps by 2."
Provide an escape hatch. Svelte's "Solve" button. If the reader gets stuck, they can reveal the answer. Always include it for tutorials, even if it spoils the puzzle.
Acknowledge the sandbox boundary. "This sandbox runs in the browser; in production, you'd…" — readers will assume sandbox behavior is full behavior unless told otherwise.
Resist over-engineering the sandbox. A sandbox that needs 12 files to demonstrate a concept is a concept too big for one chapter. Split it.
Cumulative state across pages is high-value but high-cost. If you can preserve the reader's modifications from chapter to chapter (Svelte does this), do it. If you can't, at least pre-load each chapter's sandbox with the previous chapter's solution.
Counter-intuitively, sometimes static snippets are better:
// => "result" is faster to read.Default structure for an interactive-example page section:
[H2 or H3 heading naming the concept]
[1–2 paragraphs of prose: what this is, why it matters]
[The interactive sandbox, pre-loaded with a runnable example]
[1–2 paragraphs after: what to notice, what to try modifying, what comes next]
[Optional: "Try this:" — one or two specific suggested modifications, each with a one-sentence expected result]
The "Try this:" pattern is gold. It converts passive readers into active ones. Use it.
A small, named set of callout types reduces noise. Don't invent new ones page to page.
That's seven. Resist adding an eighth.
Every page should have:
/page.md or /llms.txt) for LLM-friendly access. This is now table stakes; React, Vue, Astro, Bun, Next.js all do it.Before declaring a page or set of pages done, verify:
A short list of patterns that consistently appear in bad docs and never in praised ones:
getThing() without showing where getThing came from.foo/bar. The reader finishes without ever seeing what real code with this library looks like.When the user gives you a docs task:
For substantial doc sets, work one page at a time and confirm direction after page 1 — the patterns established in page 1 propagate, and a wrong template choice early is expensive.
references/page-templates.md — concrete copy-pasteable templates for each page type, with placeholder text and worked examples.references/source-projects.md — distilled notes on each of the 21 source projects analyzed. Use as inspiration when writing for a project that resembles one of them in shape (e.g., writing docs for an ORM → Prisma; for a runtime → Bun/Deno; for a UI library → React/Svelte; for a small validation lib → Zod).Don't read these files preemptively. Pull them in when relevant to the specific task.
npx claudepluginhub adamziel/skills --plugin skillsFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.