manual

Auto-Generated User Manual

Generate a user manual for by capturing real screenshots from the running app and analyzing its source code. Re-run it whenever features change, so the manual grows alongside the product.

⚙️ SETUP — configure for your app

This skill is a template: the app name, URLs, and Section Definitions tables below describe a placeholder app and must be configured for yours. How you do that depends on how the skill was installed:

• Copied into your project (.claude/skills/manual/SKILL.md): edit this file directly — replace every <…> placeholder and fill in the Section Definitions tables (one table per audience). Do this once.
• Installed as a plugin (read-only cache — do NOT edit this file): when run, discover the app's routes and audiences by analyzing the codebase, confirm them with the user, then generate. Optionally save the confirmed plan to docs/manuals/sections.md in the user's project so later runs reuse it.

At run time: if the Section Definitions below still contain <…> placeholders, treat them as "not configured yet" and discover from the codebase — never ask the user to edit a read-only plugin file.

The process (read source → screenshot → generate HTML → index) is identical either way. A fully filled-in example ships at examples/taskflow/SKILL.md — read it first to see what a completed skill looks like.

Usage: /manual {audience} or /manual {audience} {section}

• /manual <audience> — full manual for that audience
• /manual <audience> <section-key> — a single section only

Prerequisites Check

Before starting, verify:

1. Playwright MCP tools are available — search for browser_navigate and browser_take_screenshot. If missing, tell the user to install the Playwright MCP server (claude mcp add playwright npx @playwright/mcp@latest, Node 18+) and restart.
2. The app is reachable — either a local dev server (<your dev URLs, e.g. web on localhost:3000>) or a deployed URL (https://your-app.example). Playwright drives a real browser, so live sites work too. If a screen needs login, navigate there and ask the user to log in in the opened browser, then continue.
3. If a local app isn't running, tell the user: "Please start the dev server first (<your start command>)" — or have them give a deployed URL instead.

Section Definitions

Fill these in for your app. One table per audience (reader type). Add/remove rows freely. Route(s) = in-app paths to screenshot. Key UI elements = what to capture and describe.

<Audience A — e.g. Admin> Manual (<app name>, <base URL>)

#	Section	Route(s) to capture	Key UI elements
00	getting-started	/login, /dashboard	Login form, dashboard layout, navigation
01		/<route>	<main buttons, tables, modals, filters>
02		/<route>, /<route>/:id	<…>
…	…	…	…

<Audience B — e.g. End User / Mobile> Manual (<app name>, <base URL>, login as <role>)

#	Section	Route(s) to capture	Key UI elements
00	getting-started	/login, /register	<…>
01		/<route>	<…>
…	…	…	…

Process (per section)

Step 1: Read source code

For each route in the section:

1. Read the page component source (e.g. src/pages/<Page>.tsx).
2. Read key sub-components to understand the layout.
3. If data-manual-* attributes are present, use them for descriptions (optional).
4. Note every user-facing feature: buttons, forms, tables, modals, filters.

Step 2: Capture screenshots

Using the Playwright MCP tools:

1. Navigate to the route (browser_navigate).
2. Wait for the page to fully load.
3. Take a full-page screenshot (browser_take_screenshot).
4. For complex pages, capture multiple states: empty vs populated, modal open, filter/tab variations.
5. Save screenshots to docs/manuals/dist/screenshots/{audience}/ (inside dist/ so the published folder is self-contained).

Login credentials (local seed data): find your test accounts in <your seed source, e.g. a dev-seed script / fixtures / .env.local> and log in per audience (admin / user / …).

Step 3: Generate HTML

First, copy the theme into the output so dist/ is self-contained: manual-style.css and sidebar.js → docs/manuals/dist/shared/.

Then, for each section, write docs/manuals/dist/{audience}/{##}-{section}.html:

1. Link the shared CSS: <link rel="stylesheet" href="../shared/manual-style.css">.
2. (Optional) sidebar nav: <script src="../shared/sidebar.js"></script> at end of body.
3. (Optional) icons via Lucide CDN: <script src="https://unpkg.com/lucide@latest"></script>.
4. Reference screenshots relative to the page: <img src="../screenshots/{audience}/{file}.png">.
5. Structure: title + subtitle, screenshot <img>(s), descriptions derived from the source, step-by-step usage, info/warning boxes, prev/next nav links.
6. If using Lucide, call lucide.createIcons() at the end of body.

Step 4: Generate index

After all sections are generated, update docs/manuals/dist/index.html — the hub page linking every audience and section. Its links are relative (./shared/..., ./{audience}/...).

Step 5: Publish (optional)

The finished manual is the single self-contained docs/manuals/dist/ folder — to share it, deploy or zip just that one folder. Ask the user before publishing (it puts the manual on the public internet). Offer all three, simplest first:

A — Netlify Drop (no account, no CLI): tell the user to open https://app.netlify.com/drop and drag the dist/ folder in. Instant public URL. ⚠️ Each drop creates a new random URL (no update-in-place) — good for a quick one-off, not a stable link.

B — Netlify CLI (stable URL, update-in-place): npx netlify-cli deploy --dir docs/manuals/dist --prod First run opens a browser login and links the folder to a site; re-running deploys to the same production URL. One-time login, no manual token.

C — Cloudflare Pages (stable URL, update-in-place): npx wrangler pages deploy docs/manuals/dist --project-name <name> Authenticate once with npx wrangler login (browser OAuth — no manual token for interactive use; an API token is only needed for headless/CI). Production URL https://<name>.pages.dev stays stable across deploys.

Option	Setup	Link	Updates
Netlify Drop	none (drag folder)	new random each time	one-off only
Netlify CLI	1× browser login	stable (--prod)	same URL
Cloudflare Pages	1× wrangler login	stable (<name>.pages.dev)	same URL

Rule of thumb: one-off demo → A; a link you keep updating → B or C (C if already on Cloudflare).

Output structure

docs/manuals/dist/            ← deploy or zip THIS one folder (self-contained)
├── index.html               # hub
├── shared/
│   ├── manual-style.css     # bundled theme — restyle freely
│   └── sidebar.js           # bundled nav — edit the CONFIG block for your sections
├── screenshots/
│   └── <audience>/          # auto-captured
└── <audience>/
    ├── 00-getting-started.html
    └── ...

Style guidelines

• Write the manual in your audience's language.
• Desktop manual: max-width ~840px. Mobile manual: max-width ~480px.
• Show screenshots at natural size with a subtle border/shadow.
• Use callouts (red boxes/labels) on screenshots to highlight key UI.
• Keep step text concise — the screenshot does most of the explaining.
• Use info-boxes for common mistakes / important notes.

Important notes

• If Playwright tools are unavailable, fall back to code-analysis-only mode (generate HTML with CSS mockups instead of real screenshots).
• Never guess UI from route names alone — always read the actual component source.
• Check for data-manual-* attributes first, but don't require them.
• The manual must open directly in a browser — no build step.