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:

  ---
  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:

  ![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.