User Guide Writing

Use this skill when the deliverable is customer-facing or admin-facing documentation that helps someone complete a workflow in the product.

user-guide-writing is the documentation-cluster anchor for:

getting-started / first-success guides
tutorials and guided walkthroughs
task-based how-to articles
FAQs and support-oriented answer sets
release-facing help updates after shipped UI/workflow changes
small guide sets that combine one primary page with the minimum supporting companion docs

Read these support docs before choosing the mode or boundary:

When to use this skill

A product needs a getting-started guide that gets a new user to the first successful outcome.
A feature launch needs a tutorial or how-to article for real product users.
A help center needs a task-based article, FAQ, or troubleshooting-friendly walkthrough.
Support pain keeps recurring and the answer should become durable customer-facing documentation.
A workflow changed and the existing user-facing steps, screenshots, warnings, or prerequisites need to be updated.
A request really needs one guide plus a tiny companion packet instead of a huge mixed-purpose document.

When not to use this skill

The main job is an internal spec, architecture doc, ADR, runbook, migration plan, or builder-facing implementation guide → use technical-writing.
The main job is API reference, SDK docs, webhook docs, developer quickstarts, or developer-portal content → use api-documentation.
The main job is release notes, CHANGELOG.md, migration announcements, or shipped-change summaries → use changelog-maintenance.
The main job is a deck, launch presentation, workshop slide set, or visual review artifact → use presentation-builder.
The main job is product positioning, marketing messaging, lifecycle email copy, or launch copy → use marketing-automation.
The main job is building in-app onboarding mechanics or product-tour UX → use the relevant product/UX skill first, then use this skill for the durable written companion docs.

Instructions

Step 1: Classify one primary mode

Normalize the request before drafting.

user_guide_mode:
  primary_mode: getting-started | tutorial | how-to | faq | release-help-update
  audience: end-user | admin | manager | mixed | unknown
  experience_level: first-time | familiar | advanced | mixed | unknown
  docs_surface: help-center | docs-site | in-app-companion | pdf | unknown
  source_of_truth: product-ui | release-notes | support-tickets | sme-notes | mixed | unknown
  maintenance_need: one-off | recurring | stale-doc-rewrite | launch-critical
  output_shape: single-page | guide-plus-faq | refresh-packet | guide-set | unknown

Use one primary mode per run:

getting-started → shortest path to first success
tutorial → guided learning with context and milestones
how-to → one practical task completed quickly
faq → concise repeated questions plus route-outs to deeper guides
release-help-update → patch user-facing docs after shipped UI or workflow change

Step 2: Confirm audience, task, and route-outs

Answer these before writing:

Who will follow the doc, and what role or permissions do they have?
What exact task or outcome should they achieve?
Which prerequisites, plan limits, or environment assumptions could break the flow?
Which neighboring skills must stay out of scope?

Quick route-out table:

If the request sounds like...	Use
"Write the architecture doc / runbook / migration plan"	`technical-writing`
"Write the developer portal / SDK quickstart / webhook docs"	`api-documentation`
"Summarize what shipped this release"	`changelog-maintenance`
"Write onboarding docs / tutorial / FAQ / help article"	`user-guide-writing`
"Make a launch deck / training deck / walkthrough presentation"	`presentation-builder`

Step 3: Gather the minimum user-facing evidence

Do not draft from vibes alone. Pull the smallest credible evidence set first:

current UI labels, navigation, and states
prerequisites, permissions, and plan / edition assumptions
expected result after each important step
likely blockers, empty states, and branching conditions
screenshots or screenshot placeholders only where they reduce confusion
support questions, search terms, or recurring failure signals if available
release changes that made the current guide stale

If details are incomplete, label assumptions explicitly instead of pretending the guide is verified.

Step 4: Choose the smallest fitting structure

Use references/mode-structures.md and keep only the sections the chosen mode needs.

Rules:

If the request is one user outcome, prefer a single page.
If the task needs one main guide plus recurring blockers, use guide plus FAQ.
If the real work is patching stale pages after a release, use a refresh packet instead of rewriting a whole manual.
If one draft starts doing onboarding, daily usage, troubleshooting, and release notes all at once, split it into a small guide set.

Step 5: Emit the smallest useful artifact packet

Default output shapes:

single-page → one getting-started guide, tutorial, how-to, or FAQ page
guide-plus-faq → one main guide plus a short FAQ or troubleshooting appendix
refresh-packet → changed steps, stale screenshot list, affected companion docs, and assumptions to verify
guide-set → a bounded set such as getting-started + FAQ or tutorial + how-to follow-up

Do not ship a broad handbook when the request only needs one page and a short sync list.

Step 6: Apply user-doc writing rules

Lead with the task and audience, not implementation details.
Name prerequisites early: role, permissions, plan limits, data required, browser/app/version assumptions.
Prefer observable actions: what the user clicks, types, sees, and receives.
Keep one major outcome per page.
Call out branching conditions like role-specific UI or alternate paths.
Give the user a success check so they know the task worked.
Keep troubleshooting near the task instead of burying it in a generic appendix.
Use screenshots intentionally at confusing transitions, not after every click.
Link outward deliberately: FAQ → full guide, release-help update → affected articles, getting-started → next task.

Step 7: Run the maintenance and sync check

Use references/workflow-checklist.md and references/maintenance-signals.md before finalizing.

Verify:

The page type matches the user job.
Prerequisites and blockers appear before risky steps.
Screenshot placeholders are justified and trackable.
Related guides, FAQs, release updates, or support macros that must stay in sync are named.
Route-outs to technical-writing, api-documentation, and changelog-maintenance remain explicit when the request drifts.

Step 8: Return a brief or the finished artifact

Preferred brief shape before full drafting:

# User Guide Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:
- Output shape:

## Source material used
- Product truth / UI evidence:
- Support or release signals:
- Assumptions / gaps:

## Planned artifact packet
1. main page
2. companion FAQ / refresh list / sync note

## Writing notes
- Key user outcome:
- Known blockers / branching conditions:
- Route-outs kept out of scope:

If the user already asked for the finished artifact, produce the selected page or packet directly with the matching structure.

Examples

Example 1: First-success onboarding

Input

Write a getting-started guide for new workspace admins inviting their team and creating the first project.

Good output direction

mode: getting-started
output shape: single-page
include prerequisites, step order, success check, and next steps
keep internal implementation notes out of scope

Example 2: Release-driven doc refresh

Input

Update our help-center article for exporting reports because the Export button moved into the Reports header and only admins can choose XLSX now.

Good output direction

mode: release-help-update
output shape: refresh-packet
call out changed UI, role differences, screenshot refreshes, and affected companion docs
keep release-note summarization out of scope

Example 3: Support-to-FAQ conversion

Input

Turn these repeated billing support replies into a short FAQ for workspace owners.

Good output direction

mode: faq
output shape: single-page or guide-plus-faq
keep answers short and link to the deeper task guide where needed
surface role / plan caveats early

Example 4: Boundary with developer docs

Input

Refresh our public webhook quickstart and auth troubleshooting page for external developers.

Good output direction

route to api-documentation
explain that the main job is published developer-facing API docs, not end-user product guidance

Best practices

Choose the page type before writing the body.
Prefer one user outcome per page and one primary mode per run.
Use the smallest useful packet instead of a giant all-in-one guide.
Put prerequisites, permissions, and blockers before the user gets stuck.
Keep screenshots intentional and easy to refresh.
Use support/search/release signals to decide what to patch next.
Route internal docs, API docs, and release notes out instead of stretching the skill boundary.
Split mixed-purpose drafts into a guide set when the page starts teaching too many jobs.

user-guide-writing

User Guide Writing

When to use this skill

When not to use this skill

Instructions

Step 1: Classify one primary mode

Step 2: Confirm audience, task, and route-outs

Step 3: Gather the minimum user-facing evidence

Step 4: Choose the smallest fitting structure

Step 5: Emit the smallest useful artifact packet

Step 6: Apply user-doc writing rules

Step 7: Run the maintenance and sync check

Step 8: Return a brief or the finished artifact

Examples

Example 1: First-success onboarding

Example 2: Release-driven doc refresh

Example 3: Support-to-FAQ conversion

Example 4: Boundary with developer docs

Best practices

References