Skip to content
Get packs

Guide · Agent skill

How to use the Cypress Flake Fixer agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Cypress Flake Fixer is an agent skill that audits an existing Cypress end-to-end test suite for code patterns that cause intermittent failures, then rewrites them to wait for the real condition. It is for developers whose tests pass locally but fail in CI, teams preparing an upgrade to Cypress 15 or 16, and engineers auditing existing specs. After this guide you will know what the skill does, how to install it, how to trigger it, and what to check before trusting its changes.

Cypress Flake Fixergithub/awesome-copilot · MIT

Quick start

  1. 1Download and unzip the skill. Download the cypress-flake-fixer ZIP from this page and unzip it. The folder should contain SKILL.md, scripts/scan-cypress.mjs and the references folder.
  2. 2Place it where the agent can read it. Copy the folder to ~/.claude/skills/ for personal use, or to .claude/skills/ in your project. You can instead upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  3. 3Confirm the project meets the requirements. Check that Node.js 18 or later is installed and that the project has a package.json that lists Cypress.
  4. 4Ask for a specific problem. Describe the symptom in plain words, such as a spec that fails only in CI, or a request to remove cy.wait calls.
  5. 5Let the agent scan and record a baseline. The agent runs the scanner and, for a specific flaky spec, runs it repeatedly to record how often it fails before any change.
  6. 6Review and apply fixes by rule. Check each finding in the code, apply fixes in the order the skill gives, and commit one rule category at a time.
  7. 7Verify the result. Rerun the changed spec the same number of times as the baseline, rerun the scanner, then run the full suite once.

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file and optional scripts and reference files. When a request matches the skill's description, the agent loads its instructions and follows them. This skill covers one job: diagnosing and repairing flaky Cypress tests in a project you already have.

Once installed, the agent scans your Cypress specs for patterns such as fixed cy.wait() delays, assigned command return values, async/await, force: true, chaining after actions, one-shot expect() inside .then(), conditional testing, and APIs removed in Cypress 12 to 16 such as Cypress.env(), cy.exec(), and cy.server()/cy.route(). It then replaces each problem with the condition the delay was standing in for.

Install the cypress-flake-fixer skill

Download the ZIP for the skill from this page and unzip it. For a single user, place the folder in ~/.claude/skills/. For one project, place it in that project's .claude/skills/ folder. Alternatively, in the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.

  • Personal install: ~/.claude/skills/cypress-flake-fixer
  • Project install: .claude/skills/cypress-flake-fixer inside your repository
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

The scanner needs Node.js 18 or later. It has no dependencies and does not need Cypress installed to run the scan. The skill needs a Cypress project with a package.json, because it reads the Cypress version from that file and fixes differ by major version. Cypress must be installed in the project to run the measurement and verification steps.

  • Node.js 18 or later to run the scanner
  • A Cypress project with a package.json
  • Cypress installed in the project for measuring and verifying fixes

Trigger the skill with natural requests

You do not need to name the skill. Describe the problem in plain language. The skill's description lists the situations it applies to, including fixing flaky Cypress tests, removing cy.wait, stabilizing or hardening a suite, auditing specs, debugging "detached from the DOM" errors, and preparing an upgrade to Cypress 15 or 16.

  • "Our checkout Cypress spec passes locally but fails in CI. Find and fix the flakiness."
  • "Remove the cy.wait calls from the cypress/e2e folder and replace them with real conditions."
  • "Audit our Cypress specs for force: true and chained commands after actions."
  • "We get 'detached from the DOM' errors in the search tests. Diagnose them."
  • "Prepare this Cypress project for an upgrade to Cypress 16 and list removed APIs."

Run the scanner and follow the workflow

The agent runs the bundled scanner against your project root. You can also ask it for machine-readable output, stricter low-confidence rules, or a single file. Findings are heuristic, so the agent should open each location and confirm it before editing.

The skill asks for a baseline before changing a specific flaky spec: run it repeatedly and record how often it fails. A spec that fails 1 run in 10 needs about 30 clean runs after the fix before the fix is believable. Fixes then follow a set order, starting with rules graded error, then time-based waits, then broken retry-ability.

node ./scripts/scan-cypress.mjs <project-root> node ./scripts/scan-cypress.mjs <project-root> --json node ./scripts/scan-cypress.mjs <project-root> --strict node ./scripts/scan-cypress.mjs cypress/e2e/checkout.cy.ts

Replace fixed waits with the condition they covered

The skill does not swap cy.wait(2000) for a longer wait. It works out what the delay covered. A network request becomes a cy.intercept() registered before the trigger, followed by cy.wait('@alias'). A debounce or timer becomes cy.clock() before cy.visit() and cy.tick(ms). A render becomes a .should() on the resulting DOM. If the cause is unknown, the skill suggests opening the test in npx cypress open and reading the Command Log for the requests and DOM changes that happened during the wait.

  • Do not raise defaultCommandTimeout, add retries, or add { force: true } to make a test pass.
  • Application bugs such as double submits or race conditions are reported, not worked around in tests.
  • Fix shared custom commands in cypress/support first, since a fixed wait there runs in every test that calls it.

Verify the fix

Run the changed spec alone, then repeat it at least as many times as your baseline run. Rerun the scanner and compare counts per rule. Finally, run the full suite once to catch order dependence the change may have exposed. Keep one rule category per commit so a regression can be bisected.

Safety notes: scripts and network

The skill runs scripts: the bundled scanner, scripts/scan-cypress.mjs, is executed with Node.js against your project. The skill does not use the network. Review the scanner and the skill files before running them on code you care about, and run the skill in a repository under version control so changes can be reviewed and reverted.

  • Runs scripts: yes (scripts/scan-cypress.mjs)
  • Uses network: no
  • Measurement steps run your Cypress tests, so they execute your project's own code

What people use it for

  • Find cy.wait(number) calls in a checkout spec and replace each with an intercept alias or a DOM assertion.
  • Diagnose "detached from the DOM" errors caused by a .should() in the middle of a chain.
  • List APIs such as Cypress.env(), cy.exec() and cy.server()/cy.route() that a project must change before upgrading to Cypress 15 or 16.
  • Audit a shared cypress/support command for fixed waits that run in every test.
  • Stabilize a spec that fails once in every few CI runs by measuring a baseline before and after the fix.

Frequently asked questions

How do I install the cypress flake fixer skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

What are the requirements for the Cypress Flake Fixer?

You need Node.js 18 or later to run the scanner, a Cypress project with a package.json, and Cypress installed in the project for the measurement and verification steps. The scanner has no dependencies.

Is the Cypress Flake Fixer free?

The skill is listed under the MIT licence. Check the licence text in the repository for the exact terms.

Does the skill run scripts or use the network?

It runs scripts: the bundled scanner scripts/scan-cypress.mjs is executed with Node.js. It does not use the network. Measurement steps run your own Cypress tests.

Can it fix tests that pass locally but fail in CI?

Yes, that is a main use. The skill measures how often a spec fails, replaces fixed waits and force: true with real conditions, and reports application bugs rather than hiding them in tests.

Does it help me upgrade to Cypress 15 or 16?

Yes. The scanner reads the Cypress version from package.json and flags removed APIs, marking them error when the installed major already rejects them and warn when they will break on upgrade. Always confirm against the official migration guide.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you have an existing Cypress suite that fails intermittently in CI or needs to move to Cypress 15 or 16, and you are comfortable reviewing code the agent changes. Pick something else if you are writing new Cypress tests from scratch, since the skill targets existing suites, or if you have no Cypress project to work on.

Download the skill