Skip to main content Home Creators akillness oh-my-skills user-guide-writing
user-guide-writing Write user-facing documentation for onboarding, tutorials, task how-to guides, FAQs, help-center updates, and release-facing help refreshes. Use when the main job is helping end users or admins complete a product workflow, recover from a blocker, or understand a changed UI path. Triggers on: user guide, tutorial, getting started, onboarding doc, help article, how-to, FAQ, knowledge-base article, support doc, release help update, and customer-facing documentation. Route internal specs/runbooks to `technical-writing`, API portals/SDK docs to `api-documentation`, and release-note hygiene to `changelog-maintenance`.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/akillness/oh-my-skills --skill user-guide-writingThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository One-shot installer for the akillness/oh-my-gods agent skill bundle (80+ skills spanning agent-browser, agent-workflow, ai-research-skills, api-design, and the full god-skills catalog). Use when the user asks to add the oh-my-gods skill pack, bring in the AgenticSkills bundle, or wants every god-skill copied into Claude Code, Codex CLI, Antigravity/Gemini, and OpenCode in one step. Triggers on: AgenticSkills, agenticskills, oh-my-gods, god-skills, install oh-my-gods, bring in agentic skills bundle, install gods skills, add god skills.
Make any software agent-native with HKUDS CLI-Anything — route between four modes: install ready-made CLI harnesses via the CLI-Hub package manager (`pip install cli-anything-hub`, then `cli-hub list/search/info/install/launch`), give agents the autonomous discovery meta-skill (`npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-skill`), generate a new harness from any codebase or GitHub repo via the 7-phase pipeline (`/plugin install cli-anything` → `/cli-anything <path>`), or iterate with `/cli-anything:refine`, `:test`, `:validate`. 40+ production harnesses (GIMP, Blender, LibreOffice, OBS, ComfyUI, Ollama, Godot, QGIS, …), 2,461 passing tests, Click CLIs with REPL + `--json` output. Use when agents must drive real desktop/server software without GUI automation. Triggers on: cli-anything, cli-hub, cli-anything-hub, agent-native cli, make software agent-native, cli harness generation, /cli-anything, harness refine, HKUDS cli.
Run Comet's Opik — open-source LLM observability, evaluation, and optimization — from one routing-first skill: install the Python/TypeScript SDK, stand up a server (Comet.com cloud, Docker Compose via `./opik.sh`, or Kubernetes/Helm), wire tracing through `@opik.track` or one of 50+ framework integrations (OpenAI, Anthropic, LangChain, LangGraph, LlamaIndex, CrewAI, DSPy, Ollama, Bedrock, Vercel AI SDK, …), score outputs with LLM-as-a-judge metrics (Hallucination, Moderation, Answer Relevance, Context Precision), and run Datasets/Experiments evaluations including PyTest CI gates. Use when the user wants LLM tracing, prompt evaluation, production LLM monitoring, agent optimization, or guardrails with Opik. Triggers on: opik, comet opik, opik configure, opik.sh, llm observability, llm tracing, llm as a judge, hallucination metric, prompt evaluation, opik dashboard, opik guardrails, agent optimizer.
Related occupations SOC
Based on SOC occupation classification
name user-guide-writing description Write user-facing documentation for onboarding, tutorials, task how-to guides, FAQs, help-center updates, and release-facing help refreshes. Use when the main job is helping end users or admins complete a product workflow, recover from a blocker, or understand a changed UI path. Triggers on: user guide, tutorial, getting started, onboarding doc, help article, how-to, FAQ, knowledge-base article, support doc, release help update, and customer-facing documentation. Route internal specs/runbooks to `technical-writing`, API portals/SDK docs to `api-documentation`, and release-note hygiene to `changelog-maintenance`.
allowed-tools Read Write Edit Glob Grep compatibility Best for Markdown, help-center, docs-site, or knowledge-base workflows where the output teaches someone how to complete a task in the product rather than how the underlying system is implemented.
license MIT metadata {"tags":"user-guides, tutorials, documentation, onboarding, how-to, faq, help-center, customer-docs, product-education","platforms":"Claude, ChatGPT, Gemini","version":"2.1.0","modernization":"2026-04-13T00:00:00.000Z","hardening":"2026-04-17T00:00:00.000Z"}
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 successtutorial → guided learning with context and milestoneshow-to → one practical task completed quicklyfaq → concise repeated questions plus route-outs to deeper guidesrelease-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?
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
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
single-page → one getting-started guide, tutorial, how-to, or FAQ pageguide-plus-faq → one main guide plus a short FAQ or troubleshooting appendixrefresh-packet → changed steps, stale screenshot list, affected companion docs, and assumptions to verifyguide-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
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
Write a getting-started guide for new workspace admins inviting their team and creating the first project.
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
Update our help-center article for exporting reports because the Export button moved into the Reports header and only admins can choose XLSX now.
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
Turn these repeated billing support replies into a short FAQ for workspace owners.
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
Refresh our public webhook quickstart and auth troubleshooting page for external developers.
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.
References 