Skip to main content
Cypress App

Cypress AI Skills

Cypress AI Skills teach your AI coding agent to write, review, explain, and debug Cypress tests the way an experienced Cypress engineer would. Instead of generic test code built on brittle selectors and arbitrary waits, your AI agent produces tests that follow Cypress best practices and match the conventions already in your project.

With Cypress AI Skills, your AI agent can:

  • Generate tests that follow Cypress best practices out of the box
  • Avoid flaky patterns like weak selectors, arbitrary waits, and inter-test dependencies
  • Match your project's language, custom commands, helpers, and fixtures instead of reinventing them
  • Ground answers in official Cypress documentation rather than outdated training data
  • Run, watch, and debug tests against a live Cypress session, then fix failures in the same loop that wrote them
  • Triage recorded CI failures and flakes from Cypress Cloud without leaving the terminal
  • Behave consistently across your team, no matter who writes the prompt

Skills work with any AI coding agent that supports skills or custom instructions, including Cursor, Claude Code, and GitHub Copilot. They are published in the open source Cypress AI Toolkit.

They are free to every Cypress user: no Cypress Cloud account, no paid subscription, and no usage limits. Installing them into your agent is all it takes.

What are AI Skills?​

AI Skills are instruction sets that tell your AI agent how to approach a specific Cypress workflow: what conventions to follow, how to reason about the task, and what good output looks like.

Think of a generic AI agent as a brilliant but inexperienced new hire. Without guidance, it will do its best, but it won't know your team's standards, your project's conventions, or what good Cypress tests look like. A skill is the expert SOP manual you hand them on day one.

Available Cypress skills​

Cypress publishes five skills. They are designed to work together: cypress-author writes and fixes tests, cypress-explain reviews and explains them, and cypress-tap runs and debugs them against a live Cypress session. cypress-cloud-cli triages recorded runs and failures in Cypress Cloud, and cypress-docs grounds them all in official documentation.

cypress-author: create, update, and fix tests​

cypress-author improves how AI agents create, update, and fix Cypress end-to-end and component tests. Use it when you're writing new tests or fixing broken or flaky ones.

Before writing a single line, the skill reads your project: your Cypress config, package.json, support files, existing specs, custom commands, and fixtures. Everything it produces is shaped by what is already there, not by what a generic Cypress project might look like.

In practice, that means:

  • Selectors that hold up. The skill honors your Cypress.ElementSelector configuration if you have one. Otherwise it prefers dedicated test attributes (data-cy, data-test, data-testid, and similar) over CSS classes and DOM structure, and suggests adding a data-cy attribute to your app code when no stable selector exists.
  • Tests built for stability. It never adds arbitrary waits like cy.wait(5000), relying instead on cy.intercept() with aliases and assertions that retry automatically. Tests are written to run independently, with application state prepared programmatically rather than through slow UI flows.
  • Code that fits your project. It matches your language (TypeScript or JavaScript) and existing type patterns, and reuses your helpers, custom commands, and fixtures rather than reinventing them.
  • Only APIs your Cypress version supports. The skill detects your Cypress version and limits suggestions to what is actually available in that Cypress version.

cypress-explain: understand and review tests​

cypress-explain helps you understand, describe, and critique existing tests. Use it when auditing a suite, onboarding a new team member, or investigating a brittle test before rewriting it.

Beyond what a generic AI agent knows, this skill:

  • Classifies your question first. Whether you're asking about a Cypress concept or a specific test, it applies the right approach for each rather than treating them the same.
  • Goes deep on test review. When reviewing a spec, it identifies intent, structure, Cypress mechanics, and hidden dependencies that aren't obvious from reading the code alone.
  • Flags what will bite you. Brittle selectors, timing assumptions, unnecessary waits, UI coupling, and missing assertions are all called out explicitly.
  • Catches bad metadata. Misleading or incorrect test titles and comments are flagged and corrected, not silently accepted.
  • Uses accurate Cypress terminology. Command chains, subjects, assertions, network stubbing. It speaks Cypress, not generic testing jargon.
  • Keeps explanations concise and practical. Focused on how things are used, not exhaustive API walkthroughs.

cypress-tap: run and debug tests against a live session​

The cypress-tap skill instructs your AI agent on how to interact with a running cypress open session through the cypress tap CLI to run specs, read reporter and Command Log output, diagnose failures, and inspect the app under test from the terminal. Use it when authoring or debugging tests against a live session, so your AI agent can verify its own work rather than reporting a bare pass or fail.

The skill requires a Cypress version with access to cypress tap (15.21.0 or later) and use of a browser supported by cypress tap, and a running cypress open session to attach to. To run a headless session instead, use cypress run.

Beyond what a generic AI agent knows, this skill:

  • Reads results the way the Cypress app does. It pulls the spec overview, each test's Command Log, the error and code frame, and the console properties behind a command, drilling into a single command only when it needs to.
  • Inspects the app at the moment it broke. It pins a past command's DOM snapshot and reads the page with dom, aria, and inspect, then clears the pin when it is done.
  • Keeps its reads small. It caps the DOM, accessibility tree, and console output it pulls back, so a large page never floods your AI agent's context, and raises the caps only when it needs more.
  • Waits for the real verdict. It captures the run's start time, runs a single spec, and polls status until a fresh passed or failed arrives for that spec, so it never trusts a stale result left over from a previous run.
  • Runs against the right session. When more than one cypress open session is running, it targets the one for your project, or a specific session you name, instead of guessing.

For the full CLI reference the skill builds on, including every command, its options, and end-to-end debugging walkthroughs, see Drive Cypress with AI agents using cypress tap.

cypress-cloud-cli: triage recorded runs and failures​

The cypress-cloud-cli skill instructs your AI agent on how to investigate recorded Cypress Cloud runs through the Cloud CLI: organizations, projects, runs, specs, tests, failure screenshots, and Test Replay data, all from the terminal. Use it to triage a CI failure or flake from a Cypress Cloud URL or test ID, so your AI agent finds the root cause from recorded evidence instead of sending you to the Cloud UI.

The skill runs the Cloud CLI from the @cypress/cloud package, so it needs Node.js 22.21.0 or later, an authenticated CLI, and an organization with the Cloud CLI integration enabled. See Configure the Cloud CLI for the setup.

Beyond what a generic AI agent knows, this skill:

  • Resolves a Cypress Cloud URL directly. It reads the project, run number, and test ID from a copied Cloud test URL and queries that test straight away, instead of walking the organization and project lists to rediscover them.
  • Targets the attempt that failed. It reads a test's attempt history and passes the failed attempt number to every Test Replay query, so a flaky test's final passing retry never hides the failure it is diagnosing.
  • Reconstructs the failure from Test Replay. It pulls the commands leading up to the failed command, the XHR and Fetch network events, and the application's console logs, then correlates them to explain what broke.
  • Distinguishes flake from a reproducible failure. With no explicit flake field to rely on, it infers flake from the retry history, a failed attempt followed by a passing one, and reports the cause as unknown when the attempts are inconclusive.
  • Grounds every conclusion in evidence. It reports the run, spec, test, and timeline it inspected, and names the remaining gap when the evidence is incomplete rather than guessing.

For the full CLI reference the skill builds on, including every command, its options, and end-to-end triage walkthroughs, see Cloud CLI.

cypress-docs: look up accurate documentation​

cypress-docs gives your AI agent reliable access to accurate, up-to-date Cypress documentation. Use it to look up commands, APIs, and configuration options, or to confirm how a feature works in a specific Cypress version. It also supports the other Cypress skills, which consult official documentation while they work.

Beyond what a generic AI agent knows, this skill:

  • Searches official sources first. It routes queries to the correct section of docs.cypress.io (commands, guides, configuration, error messages) before your model reaches for Cypress knowledge it already has, which may be outdated.
  • Uses LLM-optimized documentation. The skill discovers structured Markdown content through the /llms.txt index on docs.cypress.io, giving cleaner and more reliable results than scraping HTML.
  • Grounds answers in docs, not training data. If a claim can't be verified in official documentation, it says so rather than inventing an API or behavior, reducing the chance of a confident but incorrect answer.
  • Stays version-aware. When a Cypress version is detected in your project, it scopes answers to what is available in that version and calls out differences explicitly.

Install Cypress AI Skills​

Cypress skills work with any AI coding agent that supports custom instructions, including Cursor, Claude Code, GitHub Copilot, and others.

Install with the skills CLI​

The skills package is the fastest way to install Cypress skills.

Install all skills by running:

npx skills add cypress-io/ai-toolkit

Or install each skill individually:

npx skills add https://github.com/cypress-io/ai-toolkit --skill cypress-author
npx skills add https://github.com/cypress-io/ai-toolkit --skill cypress-explain
npx skills add https://github.com/cypress-io/ai-toolkit --skill cypress-tap
npx skills add https://github.com/cypress-io/ai-toolkit --skill cypress-cloud-cli
npx skills add https://github.com/cypress-io/ai-toolkit --skill cypress-docs

Skills installed this way don't update automatically. To update your installed skills to their latest versions, run:

npx skills update

Note that the update check only tracks project-level installs, not global ones. See skills.sh for the full CLI reference, including how to list and remove installed skills.

Install with the GitHub CLI​

The GitHub CLI also supports installing agent skills.

Install all skills by running:

gh skill install cypress-io/ai-toolkit

Or install each skill individually:

gh skill install cypress-io/ai-toolkit cypress-author
gh skill install cypress-io/ai-toolkit cypress-explain
gh skill install cypress-io/ai-toolkit cypress-tap
gh skill install cypress-io/ai-toolkit cypress-cloud-cli
gh skill install cypress-io/ai-toolkit cypress-docs

Install manually​

Installation steps vary by tool.

  1. Download the skill directory from the Cypress AI Toolkit.
  2. Decide whether you want the skill installed globally or scoped to a single project.
  3. Copy it into your agent's skills location. Common locations:
    • Cursor (global): ~/.cursor/skills
    • Claude Code (project): .claude/skills
    • Other tools: check your tool's documentation for its skills or custom instructions directory.

Check your installed version​

Each skill declares its version in the frontmatter of its SKILL.md file, under the metadata.version key:

skills/cypress-author/SKILL.md
---
name: cypress-author
description: 'Creates, updates, and fixes Cypress tests ...'
metadata:
  version: 1.0.1
---

Check that file to see which version you have installed. Skills don't have automatic update notifications, so check back periodically for new releases.

How to use Cypress AI Skills​

You can invoke a skill explicitly with a slash command, or let your AI agent load it automatically when your prompt is relevant:

/cypress-author

The example prompts below show a few ways to put the skills to work. They are not exhaustive.

Scaffold tests from acceptance criteria​

This prompt describes acceptance criteria for the "Mark all complete" behavior of the TODO app in our Kitchen Sink example.

/cypress-explain Review the acceptance criteria of the "Mark all complete" flow:
- Clicking the checkbox toggles every task's completed state to completed
- All tasks move to the "Completed" task list
- The footer shows 0 active items are left
- The Clear Completed button appears

Using the Cypress Explain skill, review the existing tests to check if these requirements are already tested. If any requirements have not been asserted in tests, use the Cypress Author skill to either update the existing tests or scaffold new test(s) for the untested behavior.
tip

Pro-Tip: Connect your agent to your ticket or planning tool so it can pull in requirements and context about the behavior being changed. The more it understands about what needs to be tested, the better the output.

Generate tests that use cy.prompt()​

cy.prompt() can reduce test maintenance by using AI-driven element resolution and self-healing when the UI changes, so you depend less on brittle hand-written selectors for those steps.

You can ask your coding agent to author tests that call cy.prompt() so those behaviors are built into the specs it generates.

/cypress-author Write a new Cypress test that uses cy.prompt() to:

1. Visit the shopping cart page
2. Remove the "Vegetables" item from the cart
3. Increase the quantity of the "Chocolate" item to 6

Explain a Cypress concept​

/cypress-explain How does cy.intercept() work, and when should I use cy.wait('@alias') with it?

Look up official Cypress documentation​

Use the cypress-docs skill to get verified answers directly from docs.cypress.io instead of relying on answers that may be outdated.

/cypress-docs What configuration options are available for cy.intercept() in Cypress 13? Show me the full options object with types and defaults.

Audit a spec for quality issues​

/cypress-explain Review cypress/e2e/dashboard.cy.ts. Flag any tests that are likely to be flaky, over-coupled to implementation details, or missing meaningful assertions.

Write component tests​

Prompt for component tests when you'd rather not wire up cy.mount(), providers, stubs, and baseline assertions by hand.

/cypress-author Write component tests for the CheckoutSummary component. Review the current implementation before starting. The tests should verify it renders correctly with an empty cart, shows a line item for each product, and disables the "Place order" button when stock is unavailable.

Fix a failing test​

/cypress-author The "verify there are 2 notifications" test in notifications.cy.ts is failing with an ".notification is not visible" error. Fix it.
tip

Pro-Tip: If you are recording tests to Cypress Cloud, connect your agent to Cloud MCP to quickly iterate and resolve real-time run failures.

Run and debug a test against a live session​

With cypress open running in your project, cypress-tap can run a spec, read the failure the way the Cypress app shows it, and inspect the app at the moment it broke, all from your AI agent. See the cypress tap documentation for the full command reference.

/cypress-tap Run cypress/e2e/checkout.cy.ts against my open Cypress session, poll for a verdict, and if it fails, read the failing test's Command Log and error and inspect the app at the failing command to tell me what caused it.

Triage a recorded Cloud failure​

When a test fails in CI and was recorded to Cypress Cloud, cypress-cloud-cli can pull the run, the failing test, and its Test Replay data from the terminal, then work out the most likely cause. See the Cloud CLI documentation for the full command reference.

/cypress-cloud-cli Diagnose why this Cypress Cloud test failed: <test URL>. Inspect its failed attempt and Test Replay timeline, and tell me the most likely root cause.

Summarize test coverage in plain language​

/cypress-explain Summarize what the tests in cypress/e2e/onboarding.cy.ts cover in plain language, as if explaining it to a product manager.

Troubleshooting​

If a skill is producing incorrect output, missing a Cypress pattern, or behaving in a way that seems wrong, open an issue in the Cypress AI Toolkit repository.

How do I know a skill is triggering?​

Each agent is different, but you can usually check the conversation history to confirm your agent invoked the skill. Most agents print out that they loaded a skill.

A skill isn't triggering​

  1. Verify the skill is installed and configured in the appropriate context. Skills can be user-scoped or project-scoped, and the setup depends on your agent of choice.
  2. Skills listen for keywords and concepts, but depending on your agent, model, and other installed skills, a skill may not trigger. You can improve your odds by using the word "Cypress" in your prompt.
  3. Most agents let you verify a skill is installed and force it to run with a slash command, for example /cypress-author.

A skill is using too many tokens​

Skills sometimes prompt the agent to read foundational files like your package.json or Cypress config. Limit this by telling the agent to do "minimal exploration," or point it directly at the file you want it to use: "use my_spec.cy.js as a pattern."

Also review your AGENTS.md, CLAUDE.md, or similar agent configuration files. These often reference files that are helpful in principle but large in practice. Consider adding instructions to scope how agents use them.

The output isn't what I want​

Skills set general guidelines. Add your own steps, instructions, or anti-patterns directly in your prompt to override or extend them. The skill will mix your additions with its own.

For teams with consistent preferences, consider contributing your improvements back to the open source Cypress AI Toolkit repository, or define a project-level skill that builds on top of the defaults.

Results are slow​

The model you choose has the biggest impact on speed versus quality. For faster results, try a faster model. For higher-quality output where speed matters less, try a larger, slower model.

See also​

Skills are one part of the broader Cypress AI experience. Each of the following can extend or complement your agentic workflows:

  • Cypress AI: Overview of all AI capabilities across the Cypress App and Cloud.
  • Run Cypress tests from your AI agent: Let your agent run, watch, and debug the tests it writes against a live Cypress session.
  • cy.prompt(): Replace brittle selectors in skills-generated tests with natural language steps that self-heal when the UI changes.
  • Studio AI: Walk through your app visually after generation to catch assertions your agent might have missed.
  • Cloud MCP: Give your AI agent direct access to Cypress Cloud test results and failure data to investigate and fix issues without leaving your coding environment.
  • Cloud CLI: Query Cypress Cloud run results and Test Replay data as JSON from the terminal, the CLI the cypress-cloud-cli skill drives for terminal-based agents and your own automation.

Contents