К основному содержанию
скилл CX Codex

meticulous-simulate-and-diff — скилл для Claude Code

Скилл meticulous-simulate-and-diff запускает симуляцию сессии в Meticulous на живом URL и находит визуальные регрессии через сравнение скриншотов или разбор HTML-разметки.

ISC 9 100 установок ★ 10 обновлён 2026-10-22

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add alwaysmeticulous/skills --skill meticulous-simulate-and-diff -a claude-code
Открыть на GitHub

Что делает meticulous-simulate-and-diff

Скилл воспроизводит записанную сессию Meticulous против живого адреса приложения. Для работы требуются sessionId и appUrl. Если передан baseReplayId, инструмент сравнивает полученные скриншоты с базовым прогоном, вычисляет процент несовпадения пикселей и выявляет регрессии. Без базового прогона скриншоты сохраняются локально.

Анализ различий разбит на шаги. Сначала агент находит графические файлы в каталоге ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/. Затем для каждого кадра сопоставляются файлы метаданных .metadata.json со снимком DOM в поле before.dom и адресом страницы. Так агент отличает перекрашенные элементы от структурных изменений в вёрстке.

Перед запуском рекомендуется вызвать скилл meticulous-cli-update. Без baseReplayId автоматическое сравнение пикселей не сработает: скриншоты запишутся на диск, но сопоставлять их придётся вручную.

Какие задачи решает

  • проверить веб-приложение на визуальные регрессии после правок кода
  • локализовать расхождения в вёрстке через сравнение снимков DOM
  • отделить косметические сдвиги пикселей от изменений структуры HTML
  • воспроизвести сессию Meticulous на указанном адресе страницы

Примеры запросов агенту

  • Проверь сессию <sessionId> на <url> против базового прогона <baseReplayId>
  • Запусти симуляцию сессии <sessionId> на локальном сервере разработки без базового сравнения
  • Сравни скриншоты последней симуляции и покажи, какие CSS-классы изменились

Как установить meticulous-simulate-and-diff

1Через Skills CLI (Vercel)

npx skills add alwaysmeticulous/skills --skill meticulous-simulate-and-diff -a claude-code

2Вручную: положить файлы

~/.claude/skills/meticulous-simulate-and-diff/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/meticulous-simulate-and-diff/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о meticulous-simulate-and-diff

Как установить meticulous-simulate-and-diff в Claude Code?

Выполните в терминале команду npx skills add alwaysmeticulous/skills --skill meticulous-simulate-and-diff -a claude-code. Файл скилла будет добавлен по пути ~/.claude/skills/meticulous-simulate-and-diff/SKILL.md.

Что делает meticulous-simulate-and-diff?

Скилл запускает симуляцию сессии через meticulous simulate и анализирует расхождения в интерфейсе. Он сравнивает скриншоты, находит изменившиеся пиксели и сопоставляет разметку страниц по файлам метаданных.

Чем отличается режим с базовым прогоном от быстрой проверки?

В режиме с baseReplayId Meticulous сравнивает пиксели и HTML-разметку между двумя прогонами. Без этого параметра утилита лишь сохраняет новые скриншоты в каталог screenshots/ для ручного визуального осмотра.

Исходный текст

SKILL.md · ISC
---
name: meticulous-simulate-and-diff
description: 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.
user-invocable: true
---

# Simulate a session and analyze diffs

This skill covers running a single simulation and interpreting the results. For the `simulate` command's full option reference see the `meticulous-cli` skill's [`simulate` reference](../meticulous-cli/references/simulate.md).

> Before starting, run the `meticulous-cli-update` skill to ensure the Meticulous CLI and skills are up to date — unless it has already run earlier in this conversation, in which case skip it.

## Prerequisites

- A `sessionId` to replay
- An `appUrl` (local dev server, or leave blank to use the original recorded URL)
- Optionally: a `baseReplayId` — the ID of a prior replay to diff screenshots against. Without this, screenshots are stored but not compared.

If you don't have a `baseReplayId`, you can find one from a downloaded test run:

```bash
meticulous download test-run --testRunId=latest
# Then inspect ~/.meticulous/test-runs/<testRunId>/coverage.json
# or check the testCases[].replayId fields
```

## Step 1 — Run the simulation

### With a base replay (diff mode)

```bash
meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --baseReplayId=<baseReplayId> \
  --headless
```

Capture the full stdout. Key things to look for:

```
# Per-screenshot diff outcomes (one line each):
0.412% pixel mismatch for screenshot screenshot-1234.png (threshold is 0.100%) => FAIL!
0.000% pixel mismatch for screenshot screenshot-5678.png (threshold is 0.100%) => PASS

# Final summary block:
=======
View simulation at: https://app.meticulous.ai/projects/<org>/<project>/simulations/<headReplayId>
View comparison with base: https://app.meticulous.ai/projects/<org>/<project>/simulations/<baseReplayId>/compare-to/<headReplayId>
=======
```

**If there are no `FAIL!` lines:** the session is visually identical to the base — report no regressions, then proceed to Step 6.

Proceed to Steps 2–6 to locate and analyse any diffs, then submit feedback.

### Without a base replay (quick-check mode)

If no `baseReplayId` is available, omit it. Screenshots are still stored locally for direct visual inspection:

```bash
meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --headless
```

Then locate the replay directory (Step 2) and open the screenshots in `<replayDir>/screenshots/` to verify the UI looks correct. There are no diff images in this mode — inspection is purely visual. Steps 3–5 do not apply; still complete Step 6 after inspection.

## Step 2 — Extract the head replay ID and locate the replay directory

From the `View simulation at:` URL, extract the `<headReplayId>` (the last path segment).

To find the local replay directory created by this run:

```bash
ls -lt ~/.meticulous/replays/ | head -5
```

The most recently created entry will be the head replay's directory (named with a timestamp, e.g. `2024-01-15T12-30-45.123Z-abc123/`). Note this path — it's referred to below as `<replayDir>`.

## Step 3 — Identify which screenshots diffed

```bash
ls ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/
```

Each `.png` file here corresponds to a screenshot where a visual difference was detected. The pixel diff image highlights changed pixels in color. There are also `thumb_` prefixed thumbnail versions.

Note the filenames — they match the screenshot identifiers (e.g. `screenshot-after-event-42.png`).

## Step 4 — Analyze the HTML diff for each diffed screenshot

Each screenshot has a corresponding metadata file containing a full HTML snapshot of the page taken just before the screenshot was captured. These files are already on disk:

- **Head metadata:** `~/.meticulous/replays/<replayDir>/screenshots/<screenshotFilename>.metadata.json`
- **Base metadata:** `~/.meticulous/replays/<baseReplayId>/screenshots/<screenshotFilename>.metadata.json`

The base metadata is permanently cached when the simulation downloads the base replay, so no additional download is needed.

Read both `.metadata.json` files. The relevant fields are:

- `before.dom` — full HTML of the page at screenshot time; diff these two strings to understand what changed
- `before.routeData.url` — which page/route the screenshot was taken on

When diffing the HTML, focus on tag additions/removals, `class` attribute changes, and text content changes.

The per-screenshot stdout lines also report `mismatchFraction` (proportion of pixels that changed). If there is a pixel diff but the `before.dom` strings are identical, the change is purely visual (e.g. a color shift) rather than structural.

## Step 5 — Summarize the findings

The key output from this skill is a **high-level human-readable description of what visually changed and why**. Use the pixel diff counts, route URLs, changed class names, and HTML diffs gathered above to answer: _what did the user experience change, and which part of the UI is responsible?_

Present this in whatever format fits the current context (conversational answer, structured report, input to a calling workflow, etc.). Useful signals to draw on:

- Which routes were affected
- Which CSS classes appeared in the changed DOM regions (these usually map directly to components)
- Whether changes were structural (DOM additions/removals) or purely visual (pixel shift with no HTML diff)
- Whether the same change appears across multiple screenshots (suggesting a shared component changed) vs. isolated to one screenshot

The comparison URL logged to stdout is always worth surfacing, as it lets a human quickly verify the diff visually:
`https://app.meticulous.ai/.../simulations/<baseReplayId>/compare-to/<headReplayId>`

## Notes

- The pixel diff images at `~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/` can be opened directly for visual inspection.
- If `--baseReplayId` is omitted, no diff analysis is possible. Screenshots are still stored locally and can be compared later by re-running with `--baseReplayId` set to the head replay ID from the first run.
- For the full iterative development workflow (session discovery, per-step commits, and final cloud run), see the `meticulous-iterative-dev` skill.

## Step 6 — Report feedback to Meticulous

As the last step, after summarizing the findings, submit one brief feedback note to the Meticulous team: did the simulation and diffs help you verify the change, was anything confusing, and what information would have made the task easier?

```bash
# CLI
meticulous agent submit-feedback --message="<one or two sentences>" --outcome=<helped|neutral|hindered> --skill=meticulous-simulate-and-diff

# MCP
submit_feedback(message="<one or two sentences>", outcome="<helped|neutral|hindered>", skill="meticulous-simulate-and-diff")
```

© alwaysmeticulous · ISC · alwaysmeticulous/skills

Похожие скиллы

Все скиллы по теме «Тесты и QA» →
replica-diff Jakeschincariol Скилл replica-diff для Claude Code, Codex, Cursor и других платформ, который считает процент паритета функций клона с оригиналом и сравнивает раскладку экранов. Находит, чего не хватает, и выдаёт список в порядке сборки. CX Codex +1 1 600установок argent-screenshot-diff software-mansion Скилл argent-screenshot-diff сравнивает сохранённые или текущие скриншоты iOS-приложения и выявляет различия на уровне пикселей. Запускается при проверке UI-регрессий и изменений интерфейса. CX Codex +1 31 100установок visual-testing kindlmann Скилл visual-testing для визуального регрессионного тестирования: сравнивает скриншоты с эталонами и ловит различия на уровне пикселей, которые пропускают функциональные тесты. CX Codex +1 1 500установок visual-regression-testing aj-geddes Скилл visual-regression-testing ловит случайные визуальные изменения интерфейса: снимает скриншоты компонентов и страниц и сравнивает их между версиями. CX Codex +1 741установок visual-regression-tester patricio0312rev Скилл visual-regression-tester настраивает визуальное регрессионное тестирование: снимает скриншоты, сравнивает их с базовыми и ловит случайные изменения интерфейса. CX Codex +1 351установок visual-regression rohitg00 Плагин visual-regression проводит визуальное регрессионное тестирование интерфейса через сравнение скриншотов. Помогает отслеживать непреднамеренные сдвиги вёрстки при изменении кода. ★ 2 858звёзд репо

Из того же набора12

Весь набор →
meticulous-cli-update Скилл meticulous-cli-update проверяет, установлен ли @alwaysmeticulous/cli и свежая ли версия, и обновляет его до последней. Запускается в начале работы любого другого скилла Meticulous. CX Codex +1 9 200установок meticulous-cli Скилл meticulous-cli обучает агента работать с CLI-утилитой Meticulous: запускать воспроизведение сессий, проверять визуальные регрессии и управлять авторизацией. CX Codex +1 9 200установок meticulous-test Скилл meticulous-test запускает прогон Meticulous после правок во фронтенде и передаёт результат скиллу meticulous-review, чтобы разметить каждое визуальное изменение. CX Codex +1 9 100установок meticulous-iterative-dev Скилл meticulous-iterative-dev ведёт многошаговую правку фронтенда и после каждого шага сверяет картинку с записанными сессиями Meticulous, чтобы регрессии всплывали сразу. CX Codex +1 9 100установок meticulous-review Скилл meticulous-review разбирает результаты Meticulous, проверяет визуальные диффы и сбои проверок относительно задачи PR. Пригодится после изменений фронтенда и при проблемах с CI. CX Codex +1 9 100установок meticulous-use-session-data Скилл meticulous-use-session-data для Claude Code, Codex, Cursor и других IDE скачивает структурированные данные сессий Meticulous — записанные потоки пользователя и моки сетевых запросов. CX Codex +1 9 000установок meticulous-fix Скилл meticulous-fix исправляет отклонённые визуальные различия и сбои проверок Meticulous. Он нужен после ревью тестового запуска. CX Codex +1 5 100установок meticulous-zero-diff-task Скилл meticulous-zero-diff-task организует цикл рефакторинга или обновления библиотек во фронтенде, проверяя визуальные регрессии через Meticulous до открытия PR. CX Codex +1 5 000установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой