Skip to main content
skill CX Codex

meticulous-improve-test-env — Claude Code skill: setup guide

meticulous-improve-test-env — a skill for Claude Code that investigates why Agent swarm gets blocked on live backends. It checks missing seed data, test user permissions, auth errors, and feature flags.

ISC 129 installs ★ 10 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alwaysmeticulous/skills --skill meticulous-improve-test-env -a claude-code
Open on GitHub

What meticulous-improve-test-env does

The skill inspects setup blockers recorded by Meticulous during Agent swarm test execution against live backends. When a test cannot proceed because data records are missing, a flag is toggled off, or login fails, Meticulous flags the run as blocked.

It fetches blocker data using meticulous agent agent-swarm-setup-blockers or the MCP function get_agent_swarm_setup_blockers. After grouping issues by category, it reviews fixtures, seed scripts, user roles, deployment manifests, and .meticulous/agent-swarm-instructions.md to pinpoint needed changes.

Runs that use mocked network responses do not generate setup blockers. The skill requires the Meticulous CLI or configured MCP tools to access run logs. It also advises updating dependencies via meticulous-cli-update before troubleshooting.

What it helps with

  • fix missing seed data and fixtures for test runs
  • adjust test user roles and permissions for Agent swarm
  • enable required feature flags in the test deployment
  • diagnose test login failures and expired sessions

Example prompts for the agent

  • Why is Agent swarm blocked on the live backend?
  • Fix Agent swarm setup blockers in our test environment
  • Check test seed data and user permissions for Agent swarm

How to install meticulous-improve-test-env

1Skills CLI (Vercel)

npx skills add alwaysmeticulous/skills --skill meticulous-improve-test-env -a claude-code

2Manually: put the files in place

~/.claude/skills/meticulous-improve-test-env/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/meticulous-improve-test-env/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about meticulous-improve-test-env

How to install meticulous-improve-test-env in Claude Code?

Run npx skills add alwaysmeticulous/skills --skill meticulous-improve-test-env -a claude-code in your terminal.

What does meticulous-improve-test-env do?

It reads recorded Agent swarm setup blockers, checks codebase configs and seed data, and suggests changes to unblock tests.

What is required to run meticulous-improve-test-env?

It requires the Meticulous CLI or MCP tools, and runs must target a live backend rather than mocked responses.

Source text

SKILL.md · ISC
---
name: meticulous-improve-test-env
description: Work out what to change in a project's test environment so Agent swarm stops getting blocked when it tests against a live backend — seed better test data, widen the test user's permissions, enable feature flags, fix test login, and so on. Reads the setup blockers Agent swarm has recorded, inspects the codebase and test-environment configuration, and proposes concrete fixes. Use when Agent swarm cases are blocked by the environment rather than by the app, or when asked to "improve the test environment", "fix Agent swarm setup blockers" or "why is Agent swarm blocked".
user-invocable: true
---

When Agent swarm tests a pull request against a live backend (rather than with mocked network responses), it can only verify what the test environment lets it reach. A case it couldn't verify because of the environment — no records to act on, a test user without the right role, a feature flag that's off, a login that fails, a backend that errors — is reported as **blocked**, and Meticulous records it as a **setup blocker** with a category, the evidence the agent saw and a suggested fix. This skill turns those records into concrete changes to the project's test environment.

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

Setup blockers are only recorded for Agent swarm runs against a live backend. If the project's Agent swarm runs use mocked network responses, there will be none: tell the user, and stop.

## Step 1 -- Read the recorded setup blockers

```bash
# CLI (default: the last 30 days, newest first, 100 per page)
meticulous agent agent-swarm-setup-blockers [--since=<date>] [--category=<category>] [--runId=<swarmRunId>] [--limit=<n>] [--offset=<n>] [--project=<project>]

# MCP
get_agent_swarm_setup_blockers(since="<date>", category="<category>", runId="<swarmRunId>", limit=<n>, offset=<n>)
```

The CLI prints each category's count across all matching blockers on stderr, then a TSV table with `createdAt`, `swarmRunId`, `caseIndex`, `caseId`, `commitSha`, `category`, `blockedBy`, `caseTitle`, `summary`, `evidence` and `suggestedFix`. `--json` and MCP return the same data as `{ since, counts, setupBlockers }`. If the response says there are more results, page through them with `--offset` before drawing conclusions, or narrow with `--category`.

Start from the `counts`: the categories with the most blockers are where a fix unblocks the most cases. Then group the rows within each category by root cause — the same missing record type, the same missing role, the same flag — since many blockers usually share a handful of causes. For any blocker whose `evidence` is too thin to act on, read the full case, including the steps the agent took:

```bash
meticulous agent agent-swarm-run-case --swarmRunId=<swarmRunId> --caseIndex=<caseIndex>
# MCP: get_agent_swarm_run_case(swarmRunId="<swarmRunId>", caseIndex=<caseIndex>)
```

**If there are no setup blockers** but the user still reports Agent swarm getting blocked, list recent runs with `meticulous agent agent-swarm-runs --includeCounts` (MCP: `get_agent_swarm_runs`), open a run with many blocked cases with `meticulous agent agent-swarm-run --swarmRunId=<id> --status=blocked`, and read those cases. Cases blocked by `application` are the app's own behaviour, not the environment; treat only `environment` ones as candidates here, and fall back to the static review in Step 2 to find likely gaps.

## Step 2 -- Inventory how the test environment is set up

Before proposing anything, find out where each part of the test environment is defined. Search the codebase for:

- **Seed data and fixtures**: seed scripts, database migrations that insert data, factories, fixture files, and the commands or CI steps that run them when the environment is created or reset.
- **Test users**: how the account Agent swarm signs in with is created, which roles, permissions, organisation or plan it gets, and any allow-lists it has to be on.
- **Feature flags**: how flags are evaluated in the test environment (a flag service, environment variables, a config file) and their defaults there.
- **Authentication**: how the test login works — credentials, SSO or MFA bypasses, session lifetimes, and the environment variables or secrets it reads.
- **Backend configuration**: the environment variables, deploy manifests (for example Docker Compose, Helm charts, Terraform or a platform config file) and service URLs the test deployment uses, including which third-party services are real, sandboxed or stubbed.

Also read the project's Agent swarm instructions in `.meticulous/agent-swarm-instructions.md`, if it exists: it may already describe the test accounts or the data to expect, and can be out of date.

Record, for each blocker group from Step 1, the file or system that controls it. If a blocker's cause lives outside the codebase — a flag dashboard, an identity provider, a secrets manager, a hosted database — note that the change has to be made there.

## Step 3 -- Work out the fix for each group

Use the category to decide where to look, and the blocker's `suggestedFix` as a starting point, not a final answer — check it against what you found in Step 2.

| Category              | What it usually means                                                    | Typical fix                                                                                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `missingTestData`     | The flow needs records that don't exist for the test user                | Extend the seed data or fixtures so the test user has representative records in each state the flows need (e.g. an empty list _and_ a populated one, a draft _and_ a published item), and reseed on reset |
| `testUserPermissions` | The test user can't see or do what the flow needs                        | Give the test user the role or permissions the flows need, or add a test user per role and describe each in the Agent swarm instructions                                                                  |
| `featureFlag`         | The flow is behind a flag that is off in the test environment            | Enable the flag for the test environment or the test user; for flags under development, default them on in test environments                                                                              |
| `authentication`      | The agent couldn't sign in, or its session expired or was rejected       | Fix the test credentials or secret, disable MFA/CAPTCHA for the test user, or lengthen the test session; make sure the login works without human interaction                                              |
| `backendError`        | The backend errored, timed out or was unhealthy                          | Check the test backend's logs around `createdAt`, then fix the failing service, its configuration or its resource limits; distinguish a broken environment from a real bug the pull request introduced    |
| `externalDependency`  | A third-party service (payments, email, maps, …) was unreachable or real | Point the test environment at the provider's sandbox, or stub that service in the test environment                                                                                                        |
| `other`               | A setup problem that doesn't fit the categories above                    | Read the `summary` and `evidence`, then decide case by case                                                                                                                                               |

Prefer fixes that make the environment reliably reproducible — seed scripts that run on every reset, flag defaults in config — over one-off manual changes that drift. Don't weaken production security to unblock testing: keep any relaxed login, permissions or flags scoped to the test environment and its test users.

If a `backendError` or other blocker looks like it was caused by the pull request itself rather than the environment, say so instead of proposing an environment change — it's a bug to fix in the change.

## Step 4 -- Propose the changes

Present a short plan to the user, ordered by how many blocked cases each fix should unblock:

1. For each fix, the blocker category, the number of blockers it addresses (with one or two example case titles), the root cause and the change.
2. **Codebase changes** (seed data, fixtures, test-user setup, flag defaults, environment configuration): implement them if the user agrees, and open a pull request that explains which Agent swarm setup blockers they address.
3. **Changes outside the codebase** (a flag dashboard, an identity provider, secrets, a hosted test database): list the exact steps for the user, since you can't make them from the codebase.
4. **Agent swarm instructions**: if the agent was missing knowledge it couldn't discover — which test account to use for which role, where seeded data lives, which flows are intentionally unavailable — add it to `.meticulous/agent-swarm-instructions.md` in the same pull request. Keep secrets out of that file.

Don't change anything that affects a shared or production environment without the user's explicit go-ahead.

## Step 5 -- Verify

Once the changes are deployed to the test environment, the next Agent swarm runs should record fewer setup blockers. After at least one new run has finished, compare:

```bash
# Blockers recorded since the fix was deployed
meticulous agent agent-swarm-setup-blockers --since=<deploy time>

# Or a specific new run
meticulous agent agent-swarm-setup-blockers --runId=<swarmRunId>
```

Check that the categories you fixed have dropped, and read any blockers that remain in them: a fix that only partly worked, or a new blocker it uncovered, will show up here. Report back to the user with the before and after counts.

© alwaysmeticulous · ISC · alwaysmeticulous/skills

Similar skills

All skills for Testing and QA →

From the same set12

The whole set →
meticulous-iterative-dev meticulous-iterative-dev runs a frontend change step by step and replays recorded Meticulous sessions after each one, so a visual regression shows up where it started. CX Codex +1 9,100installs meticulous-simulate-and-diff meticulous-simulate-and-diff simulates recorded Meticulous sessions against an active application URL to detect visual UI regressions and changes in DOM structure. CX Codex +1 9,100installs meticulous-review meticulous-review reviews Meticulous results against the intended PR change, including visual diffs and failed non-visual checks. Use it after frontend pushes or when CI needs review. CX Codex +1 9,100installs meticulous-use-session-data meticulous-use-session-data — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode that downloads structured Meticulous session data — recorded user flows and network mocks. CX Codex +1 9,000installs meticulous-fix meticulous-fix applies fixes for rejected Meticulous visual diffs and failing checks. Use it after a test run has been reviewed. CX Codex +1 5,100installs meticulous-zero-diff-task meticulous-zero-diff-task drives frontend refactors and dependency upgrades toward zero visual regressions using the Meticulous test loop before you open a PR. CX Codex +1 5,000installs meticulous-increase-coverage meticulous-increase-coverage — a Meticulous skill that traces under-covered files to a real UI action, drives it with a recorded browser session and proves the coverage gain against a baseline. CX Codex +1 3,000installs meticulous Connects Meticulous visual regression testing workflows and hosted MCP server to Claude Code. It inspects UI diffs, reviews CI runs, and fixes rejected visual snapshots in chat. ★ 10repo stars

Project sponsors

Companies that keep this analytics open