# SkillPatch skill: cypress-explain This skill enables an agent to explain Cypress E2E and component tests, answer questions about Cypress APIs and behavior, and review or critique tests without writing code. It follows a structured mandatory flow: classifying the user's intent, loading relevant rule files, gathering test/config context, and producing a clear explanation. It is designed to complement a separate authoring skill by focusing purely on understanding and analysis. You (the agent) were given this URL and asked to use this skill. This is a **public** skill — no SkillPatch account, API key, or prior setup is required. Two ways to use it: **1. Use it right now** — the skill's complete file tree (SKILL.md + all reference files) is inlined below; read `SKILL.md` first, then follow it, consulting the other files as it directs. **2. Install the exact package onto disk** (recommended if you can run a shell — this reproduces the skill byte-for-byte, including any binary assets that can't be inlined): ```bash mkdir -p .claude/skills/cypress-explain curl -sSL https://skillpatch.dev/install_skill/cypress-explain | tar -xz -C .claude/skills/ ``` (`.claude/skills/` is Claude Code's convention; use whatever directory your agent loads skills from.) --- ## Skill files (4) - `SKILL.md` - `references/documentation/documentation-rules.md` - `references/explain/explain-cypress-rules.md` - `references/explain/explain-test-rules.md` ### `SKILL.md` ```markdown --- 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. 1. **Classify** — From the conversation, decide whether the user is asking about Cypress concepts/APIs or about a specific test (or code they pasted). 2. **Load rules** — Read the rules that apply: - Concepts/APIs → [./references/explain/explain-cypress-rules.md](./references/explain/explain-cypress-rules.md) - A specific test or spec → [./references/explain/explain-test-rules.md](./references/explain/explain-test-rules.md) 3. **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. 4. **Answer** — Produce the explanation or critique following those rules. 5. **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. ``` ### `references/documentation/documentation-rules.md` ```markdown # Cypress Documentation Always prefer [authoritative Cypress sources](https://docs.cypress.io) over third-party content. Review that site's `/llms.txt` file for LLM-specific guidance Before assuming that Cypress does not support a feature, behavior, or command perform a search of authoritative sources. ``` ### `references/explain/explain-cypress-rules.md` ```markdown # Explain Cypress Rules You MUST read and follow [../documentation/documentation-rules.md](../documentation/documentation-rules.md) when citing or looking up Cypress API and concepts. 1. Start With the Purpose State what the API/concept does in one sentence and focus on the problem it solves in Cypress testing. 2. Provide the Core Mental Model Explain how it works conceptually, not every detail. Describe where it fits in the Cypress workflow. 3. Show the Smallest Useful Example Include a minimal code snippet demonstrating typical usage. Prefer realistic but short examples. 4. Mention Common Use Cases and Pitfalls List 2-3 typical scenarios, such as: - Mocking API responses - Waiting for network requests - Observing request payloads Identify any commonly-encountered problems such as: - Must be defined *before* the request occurs - Cannot be chained 5. Avoid Exhaustive Details Do not include: - Full API signature - All options - Edge cases Those belong in deeper documentation. 6. Use Cypress Terminology Correctly Use accurate Cypress terms such as: - Command chain - Assertions - Test runner - Network stubbing - Subject Avoid generic testing terms when Cypress has a specific concept. 7. Prefer Concise Clarity Over Completeness If forced to choose, a clear + short explanation is preferred to a comprehensive explanation. Focus on how concepts are applied rather than the theory behind them unless instructed otherwise. The user most likely wants to understand behavior or how to use something rather than exact details on how it works. Aim for less than 20 lines total for the overall explanation (not per section). ``` ### `references/explain/explain-test-rules.md` ```markdown # Explain Test Rules You MUST read and follow [../documentation/documentation-rules.md](../documentation/documentation-rules.md) when citing or looking up Cypress API and concepts. Keep explanations scannable: use bullets and short paragraphs unless the user asks for deeper detail. When the user asks why a test is flaky or why it failed, emphasize dependencies, assumptions, and risks over structure. 1. Start With the Test's Intent Explain what the test is verifying and why it exists. Focus on the user behavior or system behavior, not the implementation. Allow the user to ask for a more comprehensive explanation of a specific area. Key questions to answer: - What feature is being tested? - What outcome should happen? 2. Outline the Test Structure Briefly describe the phases and layout of the test. 3. Explain Important Cypress Behavior Highlight how Cypress mechanics affect the test. Attempt to identify how these behaviors may contribute to test performance or stability/instability. 4. Identify Critical Dependencies or Assumptions Call out things the test relies on that may not be obvious. Identify what could break the test or cause it to behave unpredictably or be flaky. 5. Point Out Risks or Potential Problems Always mention weak points or maintainability issues. Common Cypress test risks: - brittle selectors - mixing async and sync code - timing assumptions - unnecessary `cy.wait()` - UI coupling - missing assertions - overly long tests 6. Best Practices In one short pass, note where the test diverges from what sections 1-5 already imply and from authoritative Cypress docs. 7. Corrections - Attempt to associate the title for the test and parent blocks to the identified test behavior. If misleading or incorrect titles are found then mention them in the output and suggest corrections. - Do not assume comments are always correct. If misleading or incorrect comments are found then mention them in the output and suggest corrections. ```