> Meticulous records real user sessions from a web app and replays them against each commit to catch visual regressions. > > Full AI-readable docs index (complete project setup journey + every page as markdown): https://app.meticulous.ai/llms.txt # Skills & Use cases Skills add higher-level workflows on top of the CLI and the MCP server — pre-defined workflows for reviewing test runs, running a test run end to end, debugging diffs, and more. They are Markdown files in the `SKILL.md` format, and the full source is released in [this repo](https://github.com/alwaysmeticulous/skills). They work the same way whichever way you connect. See [Setup](/docs/agents/setup#skills) for how to install and update them. - [Use cases](#use-cases) - [Ask the agent to review your test-run diffs](#ask-the-agent-to-review-your-test-run-diffs) - [Ask the agent to fix your rejected diffs](#ask-the-agent-to-fix-your-rejected-diffs) - [Ask the agent to implement a change end-to-end against Meticulous](#ask-the-agent-to-implement-a-change-end-to-end-against-meticulous) - [Ask the agent to increase coverage for your project](#ask-the-agent-to-increase-coverage-for-your-project) - [Why reject and comment?](#why-reject-and-comment) - [Install & update the skills](#install-update-the-skills) - [Skills reference](#skills-reference) --- ## Use cases There are three core flows. They differ in who reviews and who fixes, and they stack: the agent reviews for you, the agent fixes for you, or the agent does both on its own. A fourth sits outside that loop, pointing the agent at coverage rather than at a run's diffs. ### Ask the agent to review your test-run diffs > *Review the Meticulous diffs for this PR: work out which visual changes it's meant to produce from the PR description, flag and reject anything unintended, and tell me what you found.* The [`meticulous-review`](#meticulous-review) skill establishes what's expected first — from the PR description, or from the conversation if it has that context — then works through the run's representative diffs looking for the ones that don't match, using screenshots, DOM diffs and replay timelines. It reviews as a reviewer rather than as the author, and it records each unintended diff in Meticulous the way you would, rejecting real regressions and leaving a comment with its reasoning. If there's no run to review yet — the change isn't pushed, or isn't even committed — [`meticulous-test`](#meticulous-test) uploads the build and triggers the run first, then hands off to `meticulous-review`. To validate as you go instead of at the end, [`meticulous-iterative-dev`](#meticulous-iterative-dev) checks each step locally before the final cloud run. ### Ask the agent to fix your rejected diffs > *I've rejected the Meticulous diffs that are real bugs, and commented on some of them. Fix the underlying code, answer on each thread, then push and check the diffs are gone on the next run.* The [`meticulous-fix`](#meticulous-fix) skill starts from the diffs you rejected and the comments you left, fixes the underlying code, replies on each thread with the outcome, and pushes — then waits for the next CI run to confirm the diffs are actually gone. ### Ask the agent to implement a change end-to-end against Meticulous > *Upgrade React from v18 to v19. Nothing should change visually, so use Meticulous as the loop: trigger a run, fix whatever diffs come back, and repeat until it's clean — then open the PR.* The fully autonomous loop: the [`meticulous-zero-diff-task`](#meticulous-zero-diff-task) skill combines the two flows above into one the agent drives itself — implement, build, run, review its own diffs, fix what broke, run again — until the run comes back clean, and only then opens a PR. It works because the success criterion is unambiguous enough to hand over: on an upgrade, a refactor or a migration, *any* diff is a sign something broke, so there's no judgment call for the agent to get wrong and no reason for you to be in the loop until it's done. Meticulous isn't the final check here, it's what the agent iterates against. ### Ask the agent to increase coverage for your project > *I want to improve the coverage for our project. Identify the code parts that no recorded session currently reaches, record sessions that exercise them, and show me which files improved.* The [`meticulous-increase-coverage`](#meticulous-increase-coverage) skill reads the project's per-file coverage and splits what it finds in two. Code a real user flow could reach but no session happens to, it traces back to the UI action that calls it, drives that action in a real browser to record a session, and includes in a new test run. Code that never executes in a browser at all, it proposes as `.meticulousignore` entries in a PR — so the number you're measuring stops counting code that was never coverable in the first place. Two caveats worth knowing about: run it on a clean `main`, for clean coverage information. And the skill only records sessions, but still relies on the next session selection run to pick them up, so project coverage won't improve immediately. --- ## Why reject and comment? Rejecting a diff and pinning a comment on it isn't just bookkeeping — it's the task list your agent works from. - **A rejection or comment defines the scope.** `meticulous-fix` works from the diffs you rejected, plus any diff you left an actionable comment on — so there's no risk of the agent "fixing" a change you meant to keep. Use **ignore** rather than reject for noise or a flake — the skill deliberately leaves those threads alone. - **A comment is anchored to a point.** Comments carry coordinates on the screenshot, so the agent knows *where*, not just *which* — and it pulls the before/after images and the DOM diff for that same spot. - **A comment says what "fixed" means.** "This should stay left-aligned when the label wraps" is an instruction. A bare rejection only says "this is wrong", leaving the agent to infer your intent from pixels — it will try, but one sentence of intent buys you a much better fix. - **The outcome lands next to the diff.** The agent answers on your thread rather than only in its own chat window, including giving a reason if something couldn't be fixed. Because both sides read and write the same threads, the roles compose: let `meticulous-review` review a run, skim its rejections in the gallery, override or annotate the ones you see differently, then hand the set to `meticulous-fix`. --- ## Install & update the skills To install, and update, the skills into your project using [npx skills](https://github.com/vercel-labs/skills) (for the specified agents): ```bash npx skills add alwaysmeticulous/skills --skill "*" --agent claude-code --agent codex --agent cursor -y ``` --- ## Skills reference #### meticulous-review Analyze a completed Meticulous test run — compare the diffs against the PR description to see what's expected, then focus on finding and flagging potential regressions. Resolves the test run from the local repo's current commit, or from an explicit test-run ID or commit SHA. Use when asked to review Meticulous test results, when babysitting a pull/merge request's Meticulous Tests CI check, or right after implementing a frontend change yourself. #### meticulous-fix Fix the visual diffs that have been reviewed and rejected on a test run, following their review comments if given. Use when a user has reviewed the results of a test run and is handing off to an agent to implement the fixes. #### meticulous-test Run a Meticulous test run after implementing a frontend change, then hand off to the `meticulous-review` skill to classify each visual change as intended or unintended. Uploads the build once — the same build can be re-triggered against different bases without rebuilding — and it works with uncommitted changes. Use when implementing a feature autonomously end-to-end before creating a PR. #### meticulous-zero-diff-task Implement a task for which no visual diffs are expected end to end, using Meticulous to drive the implementation to a clean visual diff before opening a PR. Use when the task's whole premise is that the UI shouldn't change — a dependency/version upgrade, a code refactor, a migration, or similar. #### meticulous-increase-coverage Increase coverage for a project by tracing specific under-covered files back to a real UI action in the codebase, driving that action with a real recorded browser session, and validating the improvement with a clean coverage comparison. Also opens a PR proposing `.meticulousignore` entries for code that structurally never executes in-browser. Use when asked to increase coverage, to find untested code, or to add `.meticulousignore` entries for a project. #### meticulous-iterative-dev Iterative frontend development loop using Meticulous for per-step visual validation. Use when implementing a multi-step frontend change and want to catch visual regressions and unintended side effects at each step, before the final cloud test run. #### meticulous-simulate-and-diff Run a Meticulous session simulation against a live URL and analyze the visual output — either by inspecting screenshots directly (quick-check mode) or by comparing pixel and HTML diffs against a base replay. Use when checking whether a code change has introduced visual regressions for a specific session. #### meticulous-use-session-data Download and use structured Meticulous session data (user flows + network mocks) for testing code changes locally. Use when you need to understand what user interactions and API calls a test covers, or when you want network mocks for writing tests. --- ### Supporting skills #### meticulous-cli Overview of the Meticulous CLI tool and its global options. Use when asking about the meticulous CLI in general, available commands, or global flags that apply to all commands. #### meticulous-cli-update Checks whether the Meticulous CLI (`@alwaysmeticulous/cli`) and the skills themselves are installed and up to date, and installs/updates them if not. Invoked at the start of every other Meticulous skill, since both are under active development with frequent changes and improvements.