Skip to main content
Cypress App

Cypress AI Skills

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

info

What you'll learn

  • Why Cypress AI Skills produce better results than a generic AI tool alone
  • What each Cypress skill does and when to use it
  • How to install and use Cypress skills with your AI tool
  • How to troubleshoot a skill that isn't triggering or isn't producing what you want

With Cypress AI Skills, your AI tool 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
  • Behave consistently across your team, no matter who writes the prompt

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

What are AI Skills?​

AI Skills are instruction sets that tell your AI tool 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 tool 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 three skills. They are designed to work together: cypress-author writes and fixes tests, cypress-explain reviews and explains them, and cypress-docs grounds both in official documentation.

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

cypress-author improves how AI tools 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 tool 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-docs: look up accurate documentation​

cypress-docs gives your AI tool 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 tool 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 tool 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-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-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 tool 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.

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

Contents