Operation Guide

Overview

Use this skill to turn an interactive browser workflow into a polished customer operation guide. The expected output is a folder containing annotated images and a Markdown guide.

For local web apps, prefer the Codex in-app Browser capability when available. Capture screenshots after each meaningful user action, derive element boxes from visible UI or locator bounding boxes, then use scripts/build_guide.py to create annotated assets and guide.md.

Workflow

1. Clarify the guide scope only if needed: target URL or page, audience, business goal, and the main steps to document.
2. Use browser automation to walk through the workflow as a real customer would.
3. Capture one screenshot per meaningful step. Avoid redundant screenshots unless the UI state materially changes.
4. Record the relevant target area for each screenshot as a bounding box. Prefer actual button, input, menu, or dialog boxes from browser automation; otherwise estimate from the screenshot.
5. Create a manifest JSON following references/manifest-format.md.
6. Run scripts/build_guide.py <manifest.json> --output <output-dir>.
7. Review guide.md and annotated images. Ensure the guide is customer-facing: clear verbs, no implementation jargon, no internal debug details.

Compatibility Defaults

• The guide builder now defaults to embedded image mode.
• In embedded mode, each SVG contains the original screenshot as a base64 data URI. This is the safest choice for Markdown previewers, knowledge bases, and document conversion pipelines.
• Use --image-mode linked only when you explicitly want smaller SVG files and you know the target renderer supports local file references inside SVG.

Browser Capture Guidance

• Use screenshots that match what the customer sees, not implementation internals.
• Crop only when it improves clarity; otherwise use full-page or viewport screenshots with annotations.
• Use short step titles such as "Open the import page" or "Click New". Localize titles to the customer's language in the manifest.
• Use imperative instruction text: "Click the New button in the upper-left corner." not "The user can click..."
• Add only the annotations that help the user complete the step. One primary red box is usually better than many boxes.
• If a step has a risk or prerequisite, put it in notes instead of crowding the screenshot.

Annotation Rules

• Use red boxes for primary click or type targets.
• Use numbered labels when more than one UI element matters in the same screenshot.
• Use arrows only when the box alone does not make the target obvious.
• Keep annotation text brief. Put the full explanation in the Markdown step text.

Output Expectations

The generated folder should contain:

• guide.md: customer-facing operation guide.
• assets/step-XX.svg: annotated images referenced by the guide.
• assets/originals/step-XX-original.*: copied original screenshots.

If the user asks for Word or PDF, first generate Markdown and annotated images, then convert with the best available local tooling.

Resources

• scripts/build_guide.py: builds annotated SVG screenshots and Markdown from a manifest.
• references/manifest-format.md: manifest schema and examples.