Loom recordings to runbooks

---
name: loom-to-runbook
description: "Turn a Loom or other screen recording into a runbook of numbered steps with a screenshot each; Vivu finds the clicks, dialogs and result messages. Use when a procedure only exists as a video."
---

Loom recordings to runbooks with Vivu

This skill turns a screen recording of a procedure into a written runbook. The user hands over one or a few recordings (a Loom, a Zoom screen share, a QuickTime capture) and names the procedure each one shows. Claude indexes them in Vivu, reads Vivu's timestamped section summaries to draft an outline, searches for the moments where the pointer clicks something, a dialog opens, or a result message appears, checks every moment in frames pulled from the user's own file, and writes a Markdown runbook with one screenshot per step. With the user's approval it also creates the runbook as a Notion page.

The value is in what the presenter does without saying it. People narrate the why ("editor is the right default for most of the team") and skip the what: which tab, which button, which dialog, and what the screen shows when it worked. A transcript leaves those out and has no screenshots. Vivu searches the picture for clicks, dialogs and on-screen messages; Claude confirms each one in frames from the original file before it becomes a step, and flags screenshots that show emails, keys or customer data before anyone shares the runbook.

When to use

Use when someone asks to turn a Loom or other screen recording into a runbook, SOP, how to page or checklist, to "write up the steps in these walkthrough videos", or to document an internal admin procedure that so far only exists as a video. For a single question about one recording ("where does she change the role?"), search Vivu directly instead. When the presenter reads every step aloud and nobody needs screenshots, a transcript is cheaper. Do not index a whole library of recordings to find the few worth documenting; pick them by title first (Step 2 explains why).

Working principles

1. Report measured numbers, not estimates. When a number is an estimate, say so.
2. Nothing is "verified" until it has been checked against the source video. A search result is a candidate until Claude has looked at frames from the user's file.
3. Stop and tell the user when a required capability or tool is missing. Do not guess around it.
4. Ask the user before anything that is expensive to redo or that acts on their behalf: indexing (it uses plan minutes), sharing screenshots with personal data, and creating the Notion page.
5. A step is an action Claude has seen in a frame, not a sentence from a summary. Summaries draft the outline; frames decide what goes in.
6. Screenshots are shared content. Check each one for personal data and secrets before it is written anywhere.

What you need before starting

Check each item at the start of the run and tell the user plainly what is missing.

This skill runs once per batch of recordings. It needs no scheduler and no residential IP, because it downloads nothing from public sites.

Inputs to collect

Ask for anything missing, most important first.

1. The recordings (file paths) and the procedure each one shows. Required. For Loom, the owner can download the MP4 from the video page; if the download option is missing, the owner or a workspace admin may have turned downloads off, so ask the owner for the file.
2. Who the runbook is for. Default: a new team member who can sign in to the tool but has never done the procedure.
3. Where the runbook goes. Default: a local folder with runbook.md and images. Notion only when the user asks, with the parent page named.
4. The Vivu project. Default: a new private project named "Runbooks YYYY-MM". Admin screen recordings often show customer names and emails, and vivu_create_project makes a project visible to the whole organization unless visibility is private.
5. How to handle sensitive content in screenshots. Default: list it in review.md and let the user decide; do not edit images.

Files and state

Keep everything in one working folder on the user's computer:

runbooks/
  config.json        recordings, procedure names, audience, destination, Vivu project id
  state.json         per recording: video_id, status, search job ids, confirmed click times, steps written
  recordings/        the original video files, videos only, no subfolders
  results/           each search result saved exactly as returned, one JSON file per query
  frames/            triage frames and contact sheets
  PROCEDURE_SLUG/
    outline.md       the section outline from Step 4
    runbook.md       the runbook
    images/          step-01.png, step-02.png, ...
    review.md        what each screenshot shows that may need hiding

state.json is written after every step. A rerun reads it and skips finished work: recordings already ready are not uploaded again, searches with a saved result file are not rerun, and steps already written keep their screenshot. PROCEDURE_SLUG is a short lowercase name for the procedure, such as invite-teammate. Run every command below from inside runbooks/, because the paths are relative to it.

Step 1: Check the Vivu connector and the setup

Goal: confirm every row of What you need before touching the recordings.

1. Call vivu_get_account. If the tool is missing, tell the user to add the Vivu connector in Claude (https://mcp.vivu.ai/mcp) and stop. If it returns an account with can_create_projects: true, continue. If a later write call fails with "has not granted vivu.write", ask the user to reconnect Vivu and allow write access.
2. Run ffmpeg -version and ffprobe -version. If either is missing, stop and ask the user to install ffmpeg.
3. If the user wants Notion, fetch the parent page once to confirm access.

Done when the user has seen a short checklist with every requirement marked present or missing, and nothing required is missing.

Step 2: Measure the recordings and price the run

Goal: the user approves the index minutes and search credits before anything is uploaded.

A pile of a few hundred Loom recordings is far more than a monthly plan indexes, and most of it will never become a runbook. So this skill indexes only the recordings the user picked for the runbooks they want now.

1. Copy the recordings into recordings/ and measure each one:

ffprobe -v error -show_entries format=duration -of csv=p=0 recordings/FILE

FILE is the recording's file name including its extension, such as invite_teammate.mp4 or a QuickTime .mov. Run the command once per recording. Sum the seconds and divide by 60: that is the index minutes this batch uses. 2. Call vivu_get_usage for the user's plan and what remains this month. 3. Work out search credits. Each batch runs the three precise searches in Step 5 once, however many recordings it holds. A precise search uses 5 credits and a fast search uses 1 credit (this skill runs no fast searches), so a batch is about 15 credits (estimate; add 5 for every search rerun). 4. Show one table and wait for a yes:

If the batch does not fit, offer these levers in order: move some recordings to next month's batch (ask which runbooks are due first), then a larger plan. Do not trim recordings to save minutes; the part that gets cut is often the step nobody remembers.

Done when the user has approved the batch, and config.json lists the recordings and their durations.

Step 3: Create the project and upload

Goal: every recording in the batch shows ready in Vivu.

1. Call vivu_list_projects and reuse the user's runbook project if one exists. Otherwise call vivu_create_project with name "Runbooks YYYY-MM" (YYYY-MM is the current year and month) and visibility "private". Record the project ID in config.json.
2. Call vivu_open_upload_page with the project ID. It returns upload_url, a one time sign in link that expires in 180 seconds, so request it only when the user is ready, hand it over at once, and never store or post it.
3. The user opens upload_url in their own browser and picks the files from recordings/. If a browser tool that can attach local files is available, it can do this instead; Claude in Chrome accepts at most 10 MB per upload call. A file over the limit goes in through the Vivu web app. Never split or recompress a recording to make it fit.
4. Vivu replaces spaces and brackets in file names with underscores. Match Vivu's file names back to recordings/ after making the same replacement.
5. Poll vivu_list_videos about every 30 seconds until every video shows ready. Record each video_id in state.json.

In our test run the files were uploaded without a browser, so the browser upload itself was not exercised in our test run.

Done when every recording in config.json has a video_id in state.json and vivu_list_videos shows it ready.

Step 4: Draft the outline from the section summaries

Goal: a rough outline per recording, used to group and name the steps later.

1. For each video, call vivu_get_video_summary with project_id, video_id and include_segments: true.
2. Write outline.md: one line per section with its start and end as MM:SS, its title, and what the summary says happened.
3. Treat the outline as a table of contents. The summary text is a paraphrase; button names, field names and dialog titles come from frames in Step 6.

In our test run each section covered a page or a sub task rather than a single step. Sections on busy pages held several clicks, and where a click changed the page, the section boundary sat right on that click. The summary of the recording with no narration still described the actions it showed, so the summaries read the picture, but they left out some controls the runbook needs.

Done when outline.md exists for each recording and the user has confirmed the procedure name and where it starts and ends.

Step 5: Find the clicks, dialogs and result messages

Goal: candidate time ranges for the clicks, the dialogs and the final result message, saved as returned.

Three standing queries, all precise, because only precise returns time ranges (fast returns whole files and is for picking files in a big project, which this skill does not need):

Why these three, in this order: the outline from Step 4 says what was talked about but not where each thing was done, so the click query moves from what was said to what was done. Some clicks open a form or a confirmation, and the dialog query finds those so the step can quote the dialog's title and show it. The last step needs an expected result, and the result message query finds the toast or banner that proves it worked.

maximum_results is also the ceiling on how many ranges come back. A range can hold several clicks, so 30 leaves room for a batch of a few recordings. For a batch with many pages, raise it; the tool accepts 1 to 100. Dialogs and result messages are rarer, usually one or two per procedure, so 10 covers a batch of up to about five recordings; if either search returns exactly 10 ranges, the ceiling was hit, so rerun it with a higher value.

Run each query with vivu_search_videos (project_id, query, mode, maximum_results). It returns a job ID. Call vivu_get_search_results until complete is true; each status call can wait up to 45 seconds, so a pending search is not a stalled one. Save each completed result as returned in results/FIELD.json. Show the Vivu result page link in the reply; it expires after four hours, so it never goes into runbook.md, review.md, state.json or Notion.

Vivu's click search is region level. Its ranges contain the clicks but are often wider than one step, and the reason text names only one click per range. Treat every range as a place to look, not as a step. The capability notes behind this: action search had no measurements before this skill's test run, and visual search in general can miss moments, so an empty result does not prove there were no clicks or dialogs.

Worked example from our test run

We used three synthetic screen recordings of an admin tool (78, 60 and 36 seconds, 2.9 minutes in total), built with a script that logs the true time of every click. The narration never named a click, a button or a dialog, and the shortest recording had no sound at all, so its clicks could only be found in the picture.

All three were ready 2.2 minutes after the upload started, and indexing used 2.9 index minutes. The three searches used an estimated 15 search credits.

The click search returned 6 ranges: 6 real, 0 false. Every scripted click fell inside a range or within half a second of its start (0 missed); one range started just after the click it named. The ranges were 4.5 to 35 seconds wide, with a median of 11.8 seconds. Half of the ranges held more than one click, and the reason text named only one click per range.

The dialog search returned 3 moments: 3 real, 0 false, 0 missed. It did not return the dropdown menu, toast or tooltip we planted as look alikes.

The result message search returned 3 moments: 3 real, 0 false. A warning bar that appeared right after a key rotation was on screen inside another range, but no result named it.

Every recording in our test run showed a ring where the pointer clicked, which makes clicks easy to see in frames. Recordings without click highlights were not exercised in our test run.

Done when all three result files are saved and the user has seen the ranges listed per recording, marked as candidates.

Step 6: Check each moment and pick the screenshots

Goal: every click confirmed in frames, one screenshot per step, and a list of anything sensitive on screen.

1. Triage every range. Extract three frames (start, middle, end) and look at each one:

ffmpeg -v error -ss SECONDS -i recordings/FILE -frames:v 1 -q:v 3 frames/FIELD_hN_mid.png

FILE is the recording's file name with its extension, as in Step 2. SECONDS is a time in the range, FIELD the query field, N the result number. A range with no click, dialog or message in any frame is a false positive. Count false positives and show the count to the user. 2. Widen each click range by 2 seconds on both sides (not below 0), because range edges are approximate. 3. Build contact sheets inside each widened range. Each tile is one frame, half a second apart, 36 tiles per sheet:

ffmpeg -v error -ss START -t LENGTH -i recordings/FILE -vf "fps=2,scale=320:-1,tile=6x6" frames/sheet_STEM_START_%02d.png

START is the widened start in seconds, LENGTH its length in seconds, and STEM is FILE without its extension. Keep -t before -i so the sheets stop at the end of the range. Tile k (counting from 0, left to right, top to bottom, continuing into the next sheet) is at START + k x 0.5 seconds. 4. Find every click on the sheets: the pointer on a control, then a change on screen (a new page, a form opening, a value appearing). If the recorder draws a ring or highlight on clicks, use it. A pointer resting on a control with nothing changing afterwards is a hover, not a step. 5. For each click, extract the full size frame at the moment the pointer is on the target, before the screen changes, as that step's screenshot:

ffmpeg -v error -ss SECONDS -i recordings/FILE -frames:v 1 PROCEDURE_SLUG/images/step-NN.png

NN is the step number in two digits (01, 02, ...).

6. Read control names, field labels and dialog titles from the frame, not from the reason text, which paraphrases. Typing into a field belongs to the click on that field. The result message frame becomes the expected result.
7. Look at every screenshot for email addresses, customer names, API keys, passwords, internal URLs and the presenter's camera bubble. Write each finding to review.md with the image name and a suggested action.
8. If the frames show fewer clicks than the outline suggests, report the real count and say where the gap is. Never invent a step to fill it. A step Claude inferred without seeing the click (for example, the recording skips ahead) is marked UNCERTAIN in the runbook until the user confirms it.

Before writing the whole runbook, show the user one finished step and this field mapping, and ask whether it looks right:

3. Click **Invite member** in the top right of the Members page. A form titled "Invite a member" opens.
   ![Step 3](images/step-03.png)
   Source: invite_teammate.mp4 at 00:37

The action sentence and the expected result are Claude's reading of the frames. If a reading is wrong, the step tells the reader to click the wrong thing, which is why the user checks the sample first.

In our test run the contact sheets showed every click inside the ranges that held several, including the ones the reason text did not name, and the invite procedure became a complete runbook with an expected result. The same pass caught a screenshot with a full API key in plain text and several with team email addresses.

Done when every step has a screenshot in images/, review.md lists every sensitive item found, and the user has approved the sample step and the mapping.

Step 7: Write the runbook

Goal: runbook.md in PROCEDURE_SLUG/, ready to share once review.md is settled.

1. Write the runbook in this shape: title; purpose in one sentence; who it is for; what you need before starting; numbered steps (imperative sentence with the control name in bold, the screenshot, the source as file name plus MM:SS); expected result with its screenshot; the list of UNCERTAIN steps, if any.
2. Link sources as recording file name plus MM:SS, or the user's own Loom link with a timestamp if they give one. Never a Vivu result page link; it expires.
3. Optional: cut a short clip for a step that is hard to follow from a still. Cut with re-encoding so the clip starts exactly where asked:

ffmpeg -v error -ss START -to END -i recordings/FILE -c:v libx264 -c:a aac PROCEDURE_SLUG/clip-NAME.mp4

START and END are the clip's first and last second in the recording; NAME is a short label such as invite-form.

4. Go through review.md with the user. Replace or hide each flagged image the user wants changed before the runbook leaves the working folder.
5. Update state.json with the steps written.

Done when runbook.md exists with one screenshot per step, every item in review.md has the user's decision, and state.json records the runbook as written.

Step 8: Create the Notion page (optional)

Goal: the same runbook as a Notion page, only if the user asked for one.

Creating a page acts as the user. Name the parent page, show the complete page as it will appear (the finished runbook.md with its images), and wait for an explicit yes. If the Notion connector cannot attach local images, say so and offer two options: create the page with text only and have the user drag the images folder in, or keep the local folder as the deliverable. Sources on the page are file names plus MM:SS, never Vivu result links.

This step was not exercised in our test run: the page was rendered to a file and not created.

Done when the user has approved the rendered page and it exists under the parent they named, or the user has chosen the local folder instead.

Compliance

1. People in the recording. Loom recordings often show the presenter in a camera bubble, and screens show colleagues' names and photos. Before Step 6, ask the user to confirm the presenter agrees to the recording being reused in a runbook; pick frames where the camera bubble does not cover the step.
2. Customer data and secrets on screen. Admin recordings show real emails, customer records and keys. Step 6 lists what it sees in review.md; nothing is shared until the user has decided each item. Claude does not blur or edit images on its own and does not claim it found everything.
3. Where the videos go. Uploading puts the recordings in a Vivu project in the user's account until they delete it. Before Step 3, confirm the user may upload them; the project is private by default in this skill because the organization default makes it visible to every member. The skill never deletes anything on its own. If the user asks to remove the recordings afterwards, confirm first, because vivu_delete_video and vivu_delete_project are permanent.
4. Recordings the team did not make (vendor training, paid courses) can carry terms that forbid copying screenshots into internal docs. Ask before Step 3; use them for internal notes only.
5. If a recording shows data about minors (school or youth program records), stop and ask whether this use is allowed before indexing it.
6. The skill does no face, logo or identity recognition. It reads what is on screen and what the pointer does.
7. Creating the Notion page acts as the user and needs approval of a complete sample first (Step 8).

Known failure modes