# Guidewright Capture

> Generate or refresh user documentation for any web app by driving its live UI with Chrome DevTools or Playwright MCP, capturing screenshots, and drawing accurate red boxes around the exact element each step tells the user to click. Use whenever the user wants to document a feature, write a "how to" / step-by-step guide, refresh stale screenshots after a UI change, turn a PR or code diff into docs, or add annotated click-target screenshots to a docs site. Trigger even when the user just says "document this feature", "make a guide for X", "update the screenshots for the settings page", or "the UI changed, fix the docs" without naming this skill.

- Skill: `turbodocx/guidewright-capture` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add turbodocx/guidewright-capture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/turbodocx/guidewright-capture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: turbodocx (https://skillmd.com/u/turbodocx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/turbodocx/guidewright-capture

---


# Guidewright Capture

Produce step-by-step documentation pages for a web app where every step has a
screenshot with a **red box drawn around the precise element the user is told to
click**. The box is rendered into the live page (not painted onto the image
afterward), so it scales with the screenshot and lands exactly on the target —
no pixel-coordinate guessing.

This skill is product-agnostic: it documents whatever app you point it at, into
whatever docs site you keep. It assumes a Docusaurus-style docs repo by default;
adapt the paths and conventions to your own setup.

## Three principles that override everything else

1. **Document the path a real user actually takes.** Features usually have more
   than one way in (a toolbar button, a right-click menu, a keyboard shortcut, a
   settings deep-link). Pick the **most relevant, most discoverable** path — the
   one the typical user reaches for first — not whichever element happens to be
   easiest to click in automation. If you find a shorter or more obvious route
   than the one you started on, switch to it. When two paths are both common,
   document the primary one and mention the alternative in a tip.

2. **Write for someone who has never seen this screen.** The reader may be brand
   new to the product and to software like it, so the docs must work for **any
   skill level**. Name buttons by their visible label, say where they are ("the
   '...' button on the right of the row"), spell out every click, and don't
   assume the reader knows jargon. Short sentences, plain words, one action per
   step. Entry-level clarity is the default, not an afterthought.

3. **Commit to one Diátaxis type — you're writing a how-to.** What this skill
   produces is a **how-to guide**: a recipe that gets the reader through one real
   task, action by action. In the Diátaxis framework (tutorial / how-to /
   reference / explanation), a how-to stays a recipe — it does not teach theory or
   exhaustively catalog options. The most common way these pages rot is **blending
   types**: an explanation creeps into the steps ("here's how our permissions model
   works…"), or the page tries to document every field. Keep the steps pure; push
   the *why*, background, and concepts into a short `:::note`/`:::tip` or a linked
   **explanation** page, and push exhaustive option lists into **reference**. One
   sanity check up front: if the thing you're asked to document has **no concrete
   UI task to walk** (it's conceptual — "how X works," "why use Y"), it isn't a
   screenshot how-to at all; say so and suggest an explanation page instead of
   forcing steps and screenshots. (This is the same type-fit the companion
   `guidewright-review` skill checks for — getting it right while authoring means
   there's nothing for review to send back.)

## What this skill decides for you

Given a feature, a PR, or a code diff, work out **what to document and how**:

1. **Identify the flow.** Read the diff / changed files to figure out which UI
   feature is new or changed. Translate that to a user-facing click-path (the
   sequence of pages, buttons, and dialogs a user touches).
2. **New page or refresh?** Search the docs content directory for a page that
   already covers this flow.
   - **Exists →** read it. It already encodes the canonical step sequence and
     prose. Re-walk those exact steps against the current UI and refresh the
     screenshots; only touch prose where the UI genuinely changed.
   - **Doesn't exist →** author a new page in the right section, following the
     conventions below and the step structure of a sibling page.
3. **Walk + capture.** Drive the live UI, screenshotting each step with a red
   box on the click target (see "The red box").
4. **Write the page** into the docs repo so it's ready to commit/PR.

When in doubt about which flow or section, ask the user one question — don't
guess across multiple plausible features.

## The red box (the accurate part)

This works through **either the Chrome DevTools MCP or the Playwright MCP**, and it
works the *same way* on both: you snapshot the page, and the driver hands the exact
element you snapshot back into your injected function as a **live element handle**
(Chrome DevTools passes a `uid` in `evaluate_script`'s `args`; Playwright passes a
`ref` as `browser_evaluate`'s `target`). You box that element by injecting a DOM
overlay, so it is guaranteed to be the right one. Full mechanism, the exact snippet,
and the Chrome↔Playwright tool-name mapping: **read `references/overlay.md`.**

**On Playwright, box by DOM injection — never from coordinates.** The reason
Playwright red boxes "never land right" is placing the box from a bounding box
(`browser_snapshot` `boxes`, a highlight helper) and painting at those numbers —
which drift once the page scrolls. Injecting the overlay through `browser_evaluate`
(just like `evaluate_script`) positions the box from the element's own live rect, so
Playwright lands as accurately as Chrome DevTools. Also screenshot the page (no
`target`) — an element-target shot clips out the overlay.

The short version, per step (the same five moves on either driver — overlay.md maps
each move to the exact tool names):

1. **Snapshot** → find the element this step clicks.
2. **Evaluate** against that element: `scrollIntoView({block:'center'})`, then inject
   a fixed-position red-border overlay sized to its `getBoundingClientRect()`.
3. **Screenshot** the viewport (**never** `fullPage` — a fixed overlay misregisters
   on long pages) into the docs image folder.
4. **Evaluate** again to remove the overlay before the next step (so it doesn't
   bleed into the next screenshot).
5. **Click** the same element to advance the flow.

The box is a real DOM element the browser renders into the page, so it lands dead-on
and scales with the screenshot — same result on either driver. This was verified live
end-to-end through the Playwright MCP, and stress-checked **0px off** the target for a
scrolled element on a long page at device-pixel-ratio 1 and 2. The one rule that must
hold on both drivers: viewport screenshot, never `fullPage`.

## Output conventions (match the existing docs site)

Read a neighboring page in the target section before writing — match its style.
The conventions below assume Docusaurus; adjust for your generator. The parts that
matter regardless of stack:

- **Page file:** one page per task, e.g. `<docs-repo>/docs/<Section>/How to <Thing>.md`,
  with whatever frontmatter your site uses. A typical Docusaurus header:
  ```yaml
  ---
  title: How to <Thing>
  sidebar_position: <n>
  description: <one sentence, SEO-friendly>
  keywords:
    - <relevant>
    - <terms>
  ---
  ```
- **Screenshots:** save to your site's static image folder, one folder per page
  (e.g. `<docs-repo>/static/img/<doc_slug>/<name>.png`). Reference with the path
  your site expects and a descriptive alt that says **what is highlighted**:
  ```markdown
  ![Settings tab with the New API Key button highlighted](/img/<doc_slug>/new_key.png)
  ```
- **Steps:** `## Step N: <imperative title>`, numbered sub-instructions, screenshot
  right after the instruction it illustrates.
- **Tips/cautions:** use your generator's callouts (Docusaurus: `:::tip` / `:::note`
  / `:::caution`).
- Keep prose to the point and second-person ("you"), and follow your project's
  house style guide for everything else.

## Work in an isolated git worktree (before you touch any files)

This skill writes into a docs repo — a new or edited `.md` page plus a folder of
PNGs — and you may be running alongside other agents doing the very same thing. If
two of you author or refresh docs in the **same checkout**, you clobber each other's
files, branch, and image folders. The shared main checkout is very likely another
agent's live workspace, so treat it as off-limits and give yourself a fresh one.

Do the work in its **own git worktree**. If the **`superpowers:using-git-worktrees`**
skill is available (check your skills list), use it — it sets the isolated workspace
up for you. If it isn't installed, it's worth pointing the user at (it's the cleanest
path), but it is **not required**: a plain
`git worktree add ../<repo>-wt-<slug> <base-branch>` gives you the same isolation.

This is a *filesystem* concern, and it's separate from the *browser* concern below.
A worktree stops parallel file-writing collisions; it does nothing about the shared
browser profile — there the rule is still **one driver at a time**.

## Running the live UI safely (read before driving the browser)

**This skill requires a browser-driving MCP — either Chrome DevTools MCP or
Playwright MCP.** It's how you snapshot, inject the red-box overlay, and capture
screenshots. Before you start walking, confirm one of them is actually available:

- **Chrome DevTools MCP** — tools named `mcp__...chrome-devtools__*` (`take_snapshot`,
  `evaluate_script`, `take_screenshot`, `click`).
- **Playwright MCP** — tools named `mcp__...playwright__*` (`browser_snapshot`,
  `browser_evaluate`, `browser_take_screenshot`, `browser_click`).

**When both are available, let the person running the skill choose** — ask which
driver they want, or honor one they've already named. They may have a working setup
or a preference, and the red-box method below is identical either way, so it's their
call, not yours to hardcode. If only one is available, just use it.

If you see neither, **stop and strongly recommend the user install/enable one** (the
`chrome-devtools-mcp` or Playwright MCP server) rather than faking screenshots or
hand-drawing boxes — the whole value here is accurate, real screenshots, and that
only works through one of these MCPs. Don't proceed without it.

The browser profile may also be **shared** with other agents, and a dev stack can
be resource-sensitive. Respect these:

- **Confirm with the user before starting the app/dev stack and driving the UI.**
  Start it for the walk, then tear it down; don't spin it up speculatively.
- **Don't kill or contend for the shared browser.** Reuse the open page; don't
  relaunch the profile. If it's already in use by another agent (e.g. Playwright
  reports "Browser is already in use"), wait or coordinate — don't force it.
- **Don't auto-spawn a fleet** of agents that each drive the browser — one driver at
  a time against one shared profile.
- Get login credentials and the environment URL from the user; **never read `.env`
  or other secret files** to obtain them.

## Workflow checklist

0. Confirm a **browser-driving MCP** (Chrome DevTools *or* Playwright) is available;
   if not, stop and recommend the user enable one.
1. **Set up an isolated git worktree** for the docs repo so you don't collide with
   other agents' files (see "Work in an isolated git worktree").
2. Determine the flow from the PR/diff/feature; decide new-page vs refresh
   (search the docs content directory).
3. If refreshing, read the existing page for the canonical steps.
4. Confirm with the user, then ensure the app + your browser MCP are up and logged in.
5. For each step: snapshot → find the element → highlight (overlay) → viewport
   screenshot to the page's image folder → remove overlay → click to advance.
6. Author/update the `.md` page with frontmatter, `## Step N` sections, and image
   refs matching the conventions above.
7. Tell the user what was written and remind them to tear down the stack.