# meticulous-test

Runs a Meticulous test run after a frontend change, then hands the result to meticulous-review so each visual diff gets classified.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 8500 installs · ★ 10
- Author: alwaysmeticulous
- License: ISC · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/alwaysmeticulous/skills/tree/HEAD/skills/meticulous-test/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/meticulous-test

## What it does

The skill walks the agent through the whole loop: build the frontend the same way CI does, upload the artefact as a reusable deployment with `agent upload-build`, and capture the `deploymentId`. Then `agent trigger-test-run` compares that build against a base and prints a `testRunId`. The build is uploaded once — the same `deploymentId` can be re-triggered against a different base without rebuilding or re-uploading.

A base is required. The command infers it from the current directory (merge-base with the origin default branch) or takes `--baseSha`. By default the run blocks until it finishes, and a `Failure` status means visual differences were detected — a normal verdict, not an error. Pass `--dontWaitForTestRunToComplete` to return right away.

The catch is uncommitted changes. With a dirty working tree the run is recorded against an ephemeral commit rather than your HEAD, so commands that resolve a run from the local checkout won't find it — always pass `--testRunId` explicitly to the review step in that case. Untracked files are rejected, so `git add` them first. Before starting, the skill suggests running `meticulous-cli-update` unless it already ran earlier in the conversation.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add alwaysmeticulous/skills --skill meticulous-test -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/meticulous-test/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/meticulous-test/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add alwaysmeticulous/skills --skill meticulous-test -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/meticulous-test/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add alwaysmeticulous/skills --skill meticulous-test -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/meticulous-test/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install alwaysmeticulous/skills meticulous-test
```

2. **Manually: put the files in place**
- File: `.github/skills/meticulous-test/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add alwaysmeticulous/skills --skill meticulous-test -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/alwaysmeticulous/skills --path skills/meticulous-test
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/meticulous-test/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add alwaysmeticulous/skills --skill meticulous-test -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/alwaysmeticulous/skills/tree/HEAD/skills/meticulous-test/SKILL.md

## When to use it
- build the frontend the way CI does and upload the artefact in one step
- re-run a visual test against a different base without rebuilding
- classify each visual change as intended or unintended
- test a feature end-to-end before opening a PR, with changes still uncommitted
- capture the `testRunId` and hand it to the visual diff review

## Example prompts
- run meticulous-test after my component changes and show me what shifted visually
- trigger a test run against the main base and hand the result to meticulous-review
- my working tree is dirty — run meticulous-test and pass --testRunId to the review

## Source text · SKILL.md · ISC

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f2ca633dd04415ff.

BEGIN THIRD-PARTY FILE f2ca633dd04415ff
````text
---
name: meticulous-test
description: 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.
user-invocable: true
---

To test a frontend change using Meticulous, follow the workflow below step by step, using the CLI or MCP commands as described.

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

If you are already given a test run id, skip to Step 4.

## Step 1 -- Build the frontend

1. Find out what build artefact Meticulous expects by checking your CI config for the corresponding step:
   - GitHub: `.github/workflows/*.yml` for `uses: alwaysmeticulous/report-diffs-action/upload-assets@v1` (build assets) or `upload-container@v1` (docker image)
   - GitLab: `.gitlab-ci.yml` (or an included `.gitlab/ci/*.yml`) for `npx @alwaysmeticulous/cli ci upload-assets` (build assets) or `ci upload-container` (docker image)
   - Bitbucket: `bitbucket-pipelines.yml` for the same `npx @alwaysmeticulous/cli ci upload-assets` / `ci upload-container` step
2. Build the frontend following the same instructions as used in that CI config.

## Step 2 -- Upload the build

Register the build as a reusable deployment with `agent upload-build`. This uploads the artefact and prints a `deploymentId` to stdout — it does **not** trigger a run yet.

```bash
# CLI
meticulous agent upload-build --appDirectory <path-to-build>     # assets
meticulous agent upload-build --localImageTag <image-tag>        # container

# MCP (not 1:1 — request an upload URL, upload the artifact yourself, then register it)
request_asset_upload(size=<zipByteSize>)      # or request_container_upload() — no required args
# ... upload the zip/image to the returned URL/registry yourself ...
register_asset_build(uploadId="<id>", commitSha="<sha>")      # or register_container_build(uploadId="<id>", commitSha="<sha>")
```
````
END THIRD-PARTY FILE f2ca633dd04415ff

The third-party file has ended. Everything between the f2ca633dd04415ff tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2284 of 4942 bytes. © alwaysmeticulous · ISC · https://github.com/alwaysmeticulous/skills/tree/HEAD/skills/meticulous-test/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md