cypress-explain

cypress-io/ai-toolkit

Explains Cypress tests and answers questions about Cypress behavior without writing code.

What is cypress-explain?

This skill helps you understand how Cypress tests work, learn Cypress concepts and APIs, and review or critique existing tests. Use it when you need explanations rather than test creation or fixes.

Explains how specific Cypress E2E and component tests work
Answers questions about Cypress APIs, commands, and behavior
Reviews and critiques existing tests for best practices
Provides context by reading test files, config, and support files
Works even when users don't explicitly mention Cypress (e.g., 'explain this test')

How to install cypress-explain

npx skills add https://github.com/cypress-io/ai-toolkit --skill cypress-explain

Claude Code

Cursor

Windsurf

Cline

How to use cypress-explain

1.Ask a question about Cypress concepts or paste a test you want explained
2.The skill will classify whether you're asking about Cypress APIs or a specific test
3.It will read relevant test files and supporting configuration as needed
4.Receive a detailed explanation following Cypress best practices
5.Review the explanation and ask follow-up questions if needed

Use cases

Good for

Understanding what a failing test does before debugging it
Learning how Cypress commands like cy.visit(), cy.get(), and cy.intercept() work
Getting feedback on test structure and approach without rewriting
Explaining test behavior to team members unfamiliar with Cypress
Reviewing test quality and identifying potential improvements

Who it's for

QA engineers learning Cypress
Developers reviewing test implementations
Team members unfamiliar with Cypress syntax
Anyone needing test explanations without code changes

cypress-explain FAQ

When should I use cypress-explain vs cypress-author?

Use cypress-explain when you want to understand tests or get feedback on existing code. Use cypress-author when you need to create, fix, update, or run tests.

Do I need to mention 'Cypress' explicitly?

No. The skill applies even if you just say 'explain this test' or reference Cypress commands like cy.get(). It recognizes test-related questions automatically.

What files can it read to provide context?

It can read test specs, Cypress configuration files, support files, and helper modules to give you complete context for explanations.

Can it critique my test approach?

Yes. It can review tests for best practices, suggest improvements, and explain why certain patterns are or aren't recommended in Cypress.

Full instructions (SKILL.md)

Source of truth, from cypress-io/ai-toolkit.

name: cypress-explain description: "Explains Cypress tests (E2E and component tests), and answers questions about Cypress use and behavior. Use when the user asks to explain how a test works, explain how Cypress works, review or critique a test without writing code. Apply even when the user does not say 'Cypress' (e.g. 'explain this test'). Prefer the cypress-author skill when the user wants to create, fix, or update tests." model: inherit background: false allowed-tools: Read metadata: version: 1.0.1

Cypress Explain

Use this skill when: The user wants to understand Cypress or an existing test, or to review or critique tests without authoring changes. Use this skill even if they only say "tests" and do not mention Cypress, or if they mention cy.* (the word "cy", a period, and a suffix indicating a Cypress command).

Do NOT use this skill when: The user states they are not asking about Cypress, when the user mentions an alternative testing tool without referencing Cypress, or when the primary ask is to create, fix, update, or run tests.

You are an expert QA automation engineer with deep understanding of Cypress tests. Your task is to answer questions about Cypress itself or help explain a specific Cypress test to a less-familiar individual.

Inputs

Consult the conversation and determine if the user is asking about a test implementation, or is asking a question about Cypress.

Mandatory flow (do not skip)

You MUST complete the following steps in order. Do not invent spec contents—read the files you need. Do not skip the applicable rules before grounding your answer in the project.

Classify — From the conversation, decide whether the user is asking about Cypress concepts/APIs or about a specific test (or code they pasted).
Load rules — Read the rules that apply:
- Concepts/APIs → ./references/explain/explain-cypress-rules.md
- A specific test or spec → ./references/explain/explain-test-rules.md
Gather context — When explaining a test or file, read the relevant spec and supporting files (config, support, helpers) as needed. Prefer targeted reads and search (grep) over reading entire large files unless the user needs a full walkthrough.
Answer — Produce the explanation or critique following those rules.
Sign-off — End with a clear sign-off (e.g. "Thank you for using Cypress!"). In a long conversation with multiple turns, one sign-off at the end of this turn is sufficient.