User Guide Automation

SKILL.md

---
name: user-guide-automation
description: Reusable workflow for generating formal, detailed Markdown user guides from web applications using browser exploration or user-provided flows. Uses screenshots for every step and keeps the structure DOCX-ready.
version: 1.0.0
metadata:
  hermes:
    tags: [web, user-guide, documentation, docx, browser, screenshots, automation]
    related_skills: [dogfood, ocr-and-documents, powerpoint]
---

# User Guide Automation for Web Applications

Use this skill when the user wants to create a formal, detailed user guide from a web application, especially when the output must be a Markdown document ready for later DOCX conversion.

## Core idea

This workflow is based on browser exploration, not source-code inspection.
The guide is built from what the web app shows in a live browser session:
- page structure from `browser_snapshot()`
- visual confirmation from `browser_vision()`
- interactions with `browser_click()`, `browser_type()`, `browser_scroll()`, and `browser_press()`
- console checks from `browser_console()` when needed

If the user provides a flow, follow that flow exactly.
If the user does not provide a flow, explore the web app and infer the main user journey.

This skill currently supports one output mode:
1. **Sprint-1 / draft mode** — output Markdown only, but structure it like a final document so it can be converted to DOCX later without re-authoring.

When a reference document is provided (for example a PDF user guide), extract its structural pattern first and turn it into a reusable Markdown blueprint before writing the actual guide. Preserve:
- front matter / cover pattern
- table of contents pattern
- section lettering or numbering style
- repeated subflow pattern (e.g. daftar/tambah/detail/edit/upload/hapus/arsip)
- screenshot placement rhythm
- instructional wording style

The default file naming convention is:
- `guide.md` for the main document
- `screenshots/` for evidence assets
- one nested folder per feature or workflow stage inside `screenshots/`


## Default requirements

- Output format: Markdown (.md) only
- Style: formal
- Detail level: detailed
- Screenshots: capture every step, not only important steps
- Audience: admin, regular user, or mixed depending on the web app
- Template: use the provided structure as a Markdown blueprint; do not generate DOCX in this skill


## Slash-command intake form

When the user runs `/user-guide-automation`, ask for the minimum required information in a copy-ready format:

- URL:
- Lokasi output:
- Scope: full site / fitur tertentu (sebutkan fiturnya)

Optional but recommended:
- Role:
- Credential:
- Flow:
- Template path:
- Output filename:
- Catatan khusus:

Rules:
- If the user chooses a specific feature scope, stay within that feature unless related navigation is needed.
- If the user chooses full site, explore the main journeys and major feature groups.
- If credentials are provided, use them only for the requested app and flow.

## Recommended workflow

### 1) Intake
Collect or confirm:
- target web app URL
- target user role, if relevant
- user-provided flow, if any
- DOCX template path
- output filename or folder
- whether the guide should cover one feature or the whole workflow
- screenshot output directory behavior (default: create `screenshots/` inside the output folder)

If the user did not provide a flow, proceed with exploration.

When the user provides only a top-level output folder, create this structure:
```
{output_dir}/
├── guide.md
├── screenshots/
│   ├── dashboard/
│   ├── ai-characters/
│   └── ...
└── references/
```
Use one subfolder per feature, page group, or workflow stage so screenshots stay organized. Use lowercase kebab-case folder names when possible.

### 2) Explore the web app
Open the app and identify the real user journey.
Use the browser tools in this order whenever useful:
- `browser_navigate(url=...)`
- `browser_snapshot()`
- `browser_vision(question=..., annotate=true)`
- `browser_click(ref=...)`
- `browser_type(ref=..., text=...)`
- `browser_scroll(direction=...)`
- `browser_press(key=...)`
- `browser_console(clear=true)` after navigation or significant interaction

For pages with animations, lazy loading, or scroll-revealed content, do not judge a section from one viewport alone. Scroll in small increments, pause briefly, then re-check with `browser_snapshot()` and/or `browser_vision()` before deciding content is missing or empty.

During exploration, collect only the UI details needed for the guide:
- page title
- menu names
- button labels
- field labels
- success/error messages
- breadcrumb/path names

Do not over-extract text. Keep it lean.

### 3) Build the step list
Create a step list that matches the real interaction sequence.
If a user flow exists, preserve the provided order.
If not, infer a practical order from the app UI.

Each step should include:
- step number
- action verb
- target UI element or page
- short explanatory note if needed
- screenshot reference

For sprint-1 Markdown drafts, organize the step list into document-like sections first, then steps. Use the same top-level section order that a DOCX template would later expect, so the MD stays conversion-friendly.

### 4) Capture screenshots for every step
Take screenshots for all steps, including intermediate ones.
Use screenshots as instruction illustrations, not as bug evidence.

If a step changes the page state, capture the new state immediately.

Practical lesson: when the workflow includes login, capture a dedicated login screenshot before entering the protected area. Do not reuse a later dashboard screenshot as evidence for the login step; keep the login step, post-login dashboard, and feature page as separate screenshots so the guide stays clear and accurate.

### 5) Write the guide text
Write formal Indonesian.
Preferred structure:
- title/cover
- table of contents if the template supports it
- section headings
- numbered steps
- concise but detailed instructions
- screenshot captions
- notes or warnings only when needed

Keep wording instructional and neutral.
Avoid QA language such as severity, issue, or defect.

### 6) Write the Markdown guide
If a template or blueprint is provided:
- reuse the existing Markdown structure
- preserve header/footer-equivalent sections only as text blocks
- keep the hierarchy consistent
- do not switch the output to DOCX in this skill

If the structure is blank:
- populate it cleanly with the generated guide content

### 7) Verify the final Markdown
Check that:
- all steps are present
- screenshots match the correct steps
- the language is formal
- the Markdown structure is complete and readable
- the output filename is correct

## When to use user-provided flow vs exploration

Use the user’s flow when:
- the user already knows the exact process
- the app is sensitive or complex
- the workflow must match a SOP exactly

Use exploration when:
- the user does not know the exact steps
- the app is unfamiliar
- the user wants the guide to be discovered from the live UI

## Token-saving rules

- Do not read or restate entire pages unless necessary
- Prefer `browser_snapshot()` for structure and refs
- Prefer `browser_vision()` only when layout or visuals matter
- Reuse a stable guide template
- Keep captions short
- Avoid repetitive descriptions across steps

## Important distinctions from dogfood

Dogfood is QA-oriented and looks for bugs.
This skill is documentation-oriented and looks for user actions.

Shared pieces borrowed from dogfood:
- browser exploration
- screenshots per step
- console checks when useful
- systematic flow execution

Differences from dogfood:
- no severity classification
- no bug reporting
- no reproduction section
- output is a user guide, not a QA report

## Suggested output pattern

- If the user gives a template path, treat it as a Markdown blueprint reference rather than a DOCX target
- If the user gives a duplicateable blank template, copy its structure into Markdown first
- Save the final document as `.md`
- Optionally save screenshot assets alongside it if needed for review


### Markdown blueprint mode
When the user wants a DOCX-like structure in Markdown first:
- start with the same cover/TOC/header order the final document will use
- keep section numbering stable
- preserve repeated subsection patterns across modules
- use short placeholder captions for screenshots
- keep the document ready for later DOCX conversion without changing the content hierarchy

## Practical checklist

Before finishing, confirm:
- [ ] The guide follows the right flow
- [ ] Every step has a screenshot
- [ ] The writing is formal
- [ ] The template formatting is preserved
- [ ] The Markdown file is complete and usable