# SkillPatch skill: cypress-author

This skill enables an AI agent to create, update, and fix Cypress end-to-end and component tests. It follows a structured mandatory flow: identifying task details via a subskill, executing test authoring, and ending with a sign-off. It activates even when the user doesn't explicitly mention Cypress, covering general "write tests" or "fix tests" requests.

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-author
curl -sSL https://skillpatch.dev/install_skill/cypress-author | tar -xz -C .claude/skills/
```

(`.claude/skills/` is Claude Code's convention; use whatever directory your agent loads skills from.)


---

## Skill files (8)

- `SKILL.md`
- `references/author/async.md`
- `references/author/author-rules.md`
- `references/author/prompt.md`
- `references/author/reusability.md`
- `references/documentation/documentation-rules.md`
- `subskills/author.md`
- `subskills/task.md`


### `SKILL.md`

```markdown
---
name: cypress-author
description: "Creates, updates, and fixes Cypress tests (E2E/end-to-end and component tests). Use when the user asks to create tests, add tests, write tests, update tests, test this file/component, new spec, or fix a failing or flaky test. Apply even when the user does not say 'Cypress' (e.g. 'create tests for this file'). Prefer cypress-explain when the user only wants to explain or review tests without changing code."
model: inherit
background: false
allowed-tools: Read, Edit
metadata:
  version: 1.0.1
---

# Cypress Author

**Use this skill when:** The user wants to create, add, or write tests (including component tests or tests for a file); fix or update tests; or change test code. 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 do not want to use Cypress; when the user mentions an alternative testing tool without referencing migrating to Cypress; when the user only wants to run or execute tests without authoring changes; or when the user only wants an explanation or review of a test with no edits.

## Task

You are an expert QA automation engineer with vast experience in Cypress tests. Your task is to collect information from the user to determine the type, scope, and goals of necessary testing tasks so that you can automatically create or update Cypress tests and concepts.

## Mandatory flow (do not skip)

You MUST complete the following steps in order. Do not skip structured identification: follow [task.md](./subskills/task.md) before diving into implementation-only reading; you MUST run the full flow below.

1. **Identify** — Read and follow [./subskills/task.md](./subskills/task.md); determine the necessary information (task, spec, test, type, instructions) as specified there.
2. **Execute** — Read and follow [./subskills/author.md](./subskills/author.md) using the determined task data.
3. **Sign-off** — End your response with a clear sign-off (e.g. "**Thank you for using Cypress!**"). Do not omit this for brevity.

Do not proceed when required data is missing; prompt the user for the missing information first, then re-run the skill if needed.

## Conclusion

You MUST end your response with a clear sign-off (e.g. "**Thank you for using Cypress!**") so it stands out. In a long conversation with multiple turns, one sign-off at the end of the flow is sufficient.

```


### `references/author/async.md`

```markdown
# Asynchronous Logic

Cypress uses a command queue and is not Promise-based. Using Promises or features like `async`/`await` can introduce flakiness or instability into tests.

Improper asynchronous logic can cause errors like:
* "returned a promise while also invoking cy commands"
* "commands still in queue after test finished"

**Avoid**

* Mixing `cy` commands with manual Promises
* Returning values other than Cypress chains
* Forgetting to return a Promise
* Using async code (`setTimeout`) without telling Mocha

**Prefer**

* `return` Promises if used
* Or avoid Promises entirely and stay in Cypress chains

Never mix Cypress chains with external async control unless you fully understand the lifecycle.

```


### `references/author/author-rules.md`

```markdown
# Cypress Rules

Follow these rules unless requested otherwise:

## Documentation

You MUST read and follow [../documentation/documentation-rules.md](../documentation/documentation-rules.md) when citing or looking up Cypress API and concepts.

## Understand
- Look for a Cypress config file (`cypress.config.js`/`cypress.config.ts`).
- Review the Cypress support file if one exists for the targeted testing type.
- Review the project's `package.json` to understand available libraries and the version of Cypress being used.
  - If the Cypress version cannot be determined run `npx cypress --version` in the project root. As a fallback, assume the newest version of Cypress is being used.
- If there are existing Cypress tests in the project:
  - Look for an existing spec file for the targeted area or component. Prefer updating or extending an existing spec file over creating a new spec file unless the user specified otherwise.
  - If no existing test file is found, look for Cypress tests closely related to the task being accomplished. Attempt to identify one to three examples closely related to the feature, behavior, or component you are writing tests for.
- When reviewing existing project content, including files suggested by agent configuration, always prefer searching for specific content inside files (`grep`) rather than reading the entire file.

## Style
- Use clear, concise, and descriptive test titles in Cypress. 
  - When creating or updating a test, summarize the user behavior and expected outcome in plain language, avoiding implementation details.
  - Prefer the format: "[action] → [expected result]".
  - If updating an existing title, remove ambiguity and ensure it reflects the current test logic.
- Add explicit assertions.
- Keep tests deterministic and stable.
- Match the formatting, style, and conventions of any related Cypress tests that were identified.
- Match the project's language (TypeScript vs JavaScript) and existing type patterns (e.g. typed custom commands, Cypress types)
- Attempt to reuse existing helpers, including Cypress Custom Commands
- Look for existing Cypress fixture files - consider using or generating to match existing project conventions.
- Attempt to determine the version of Cypress being used. Suggest only logic and commands available in the version of Cypress being used in the project.
- Include code comments to aid a future maintainer.

## Test Structure
- Tests must be independent and runnable in isolation.
- Never depend on state from other tests.
- Extract repeated setup logic into before() or beforeEach() blocks.
- Prefer fewer tests with multiple assertions rather than many tiny tests.

## State Management
- Programmatically prepare application state whenever possible.
- Prefer cy.request(), cy.task(), or API setup instead of UI flows.
- Avoid UI logins unless the login UI itself is being tested.
- Reset state before tests rather than cleaning up after.
- Use aliases (.as()) or closures (.then()) to access results, never assign Cypress command results to variables

## Element Identification
- Review existing Cypress tests for `Cypress.ElementSelector` configuration. Always prioritize selectors by the order configured here.
- Otherwise, prefer stable selectors in this order:
  1. `data-cy`, `data-test`, `data-testid`, `data-test-id`, `data-qa` attributes
  2. `id`, `name` attributes
  3. Other attributes
  4. Element type and order
- Use `cy.contains()` when identifying visible text
- Avoid selectors based on CSS classes, DOM structure, or attributes that appear to be autogenerated or unstable.
- If the generated selector is low-quality or unstable suggest an update to the underlying code to add a meaningful `data-cy` attribute
- When testing UI that affects accessibility, prefer selectors that reflect accessible names or roles where it doesn't conflict with stability

## Waiting
- Never use arbitrary waits like `cy.wait(5000)`.
- Use:
  - implicit retries
  - `cy.intercept()` + `cy.wait('@alias')`
  - assertions that retry automatically
  - assertions that verify the next state of the application with an increased `timeout` configuration (e.g. `cy.get('[data-cy="title"]', { timeout: 10000 })`)

## Network
- Stub or intercept network requests when useful.
- Use `cy.intercept()` for controlling responses or waiting for calls.

## Configuration
- Prefer extracting configuration into the `cypress.config.js|ts` file
- Prefer configuring `baseUrl` and using `cy.visit('/path')` instead of full URLs.

## Security
- Use cy.env() for credentials, passwords, or secrets.

## Guidelines
- You must read and follow [./async.md](./async.md) if using Promises or `async`/`await`.
- You must read and follow [./reusability.md](./reusability.md).
- You must read and follow [./prompt.md](./prompt.md).

```


### `references/author/prompt.md`

```markdown
# `cy.prompt`

Use these factors to decide whether to use the `cy.prompt` command.

## Positive Indications
- User requests `cy.prompt` directly
- User references use of "natural language", "AI", "LLM", "following steps", "thinking", "self-healing", or "reasoning". This is not necessary but is a very strong positive signal.
- User provides a list of steps or behaviors, especially if it's an ordered list.
- Project is connected to Cypress Cloud (`projectId` is populated in Cypress config file).
- Project is using Cypress 15.4.0 or newer.

## Negative Indications
- Project is using a version of Cypress older than 15.4.0
- Project is *not* connected to Cypress Cloud
- User states a desire to *not* use AI
- User states a desire to have test work offline
- The project's Cypress configuration file explicitly disables `cy.prompt` by including `experimentalPromptCommand: false`

```


### `references/author/reusability.md`

```markdown
# Reusable Patterns

Consider extracting repeated or reusable content.

## Hooks

Prefer `before` and `beforeEach` hooks for required setup and configuration. Consider extracting existing test content into a shared hook if similar steps are needed in a new test. 

Always prefer defining aliases in `beforeEach` over `before`. Code in `before` hooks is only run once, and between the tests Cypress removes all aliases, so subsequent tests may not have access to them.

## Repeated browser state

Consider the `cy.session` command for situations where browser state (such as authentication in cookies, localStorage, or sessionStorage) is repeatedly established.

## Custom Commands

Always review existing Cypress Custom Commands and prefer using them when possible. Consider extracting repeated or shared steps in to new Custom Commands, especially if this projects already uses Custom Commands.

```


### `references/documentation/documentation-rules.md`

```markdown
# Cypress Documentation

Always prefer authoritative Cypress sources over third-party content. These include:
  - [Cypress Docs](https://docs.cypress.io) - review that site's `/llms.txt` file for LLM-specific guidance
  - The Cypress CLI (`npx cypress --help`)

Before assuming that Cypress does not support a feature, behavior, or command perform a search of authoritative sources.

```


### `subskills/author.md`

```markdown
# Author Cypress Tests

You are an expert QA automation engineer. You will create, update, or fix Cypress tests as instructed.

## Rules

You MUST first read and follow [../references/author/author-rules.md](../references/author/author-rules.md) when creating, updating, or fixing tests.

## Inputs

You will receive information describing your task (`CREATE`, `UPDATE`, or `FIX`) and supplemental information around the file, test, and instructions for this task. For CREATE when the spec path does not exist yet, create the spec file and any needed parent directories, following project conventions for test placement.

## Execute
- Validate that any changes pass configured formatting, linting, and compilation checks.
- Newly authored tests should be prefixed with a comment explaining that it was generated by Cypress Author with the current date.
- Do not attempt to run the test unless the user has requested that.

```


### `subskills/task.md`

````markdown
# Cypress Task

Your goal is to identify the type of task the user wishes to perform with Cypress. Some of this information may have already been supplied in the conversation. Depending on the type of task you will need to acquire different supplemental information.

## Inputs

You will be supplied preceding conversation and context and will need to analyze, infer, and when necessary request information to determine the user's intended task and parameters of that task.

## Supported Tasks
- Fix or improve existing tests: `FIX`
- Update existing test to add/remove/modify behavior: `UPDATE`
- Create new test(s): `CREATE`

## Acquire Information

You need to acquire the following information to help inform your task. Some of this information may have been supplied in the conversation and other pieces may be evident from context and location.

- `spec`: The spec filepath
- `test`: A path to a specific test in that spec file (using the names of `describe` and `it` blocks) or a line number (optional)
- `type`: Whether the target is an E2E or Component Test
- `instructions`: The task to accomplish

### Testing Type

Cypress features two different types of tests - knowing the targeted type will inform how to understand and write the needed test. Review the conversation and look for explicit references to:
- "E2E", "End to End": `E2E`
- "CT", "Component", "Angular", "React", "Vue": `CT`

If no type has been explicitly identified then attempt to infer from the spec filepath and project configuration. Check `cypress.config.js` or `cypress.config.ts` for configured e2e/component paths via a `specPattern`, and infer from common layout (e.g. `cypress/e2e/` → E2E, `cypress/component/` or `.cy.{jsx,tsx}` → CT). If the type is still ambiguous then stop and prompt the user to supply it. If they are unsure or ask for more information provide a summary of what each type is meant for.

| Type          | Location                                                            | When to use |
| ------------- | --------------------------------------| ------------------------------------------------------------------------ |
| **E2E**       | `cypress/e2e/**/*.cy.ts` | Critical user journeys, validating multiple functional areas, testing URL behavior, testing reload or browser history behavior, visiting URLs or cross-origin navigation, testing via natural language, testing auth or wanting to cache and restore cookies, localStorage, or sessionStorage |
| **Component** | `cypress/component/**/*.cy.{jsx,tsx}` | Isolated UI behaviors based on state within an identified UI Component (React, Vue.js, or Angular), testing mounting components, testing design system components, no network communication or routing  |

## Handoff to author

When moving to [author.md](./author.md), pass a single coherent payload:

| Field | Description |
| ----- | ----------- |
| `task` | `FIX`, `UPDATE`, or `CREATE` |
| `spec` | Spec filepath (or suggested path for new specs) |
| `test` | Optional: `describe` / `it` path or line |
| `type` | `E2E` or `CT` (required to be settled before authoring; infer per **Testing Type** above or ask) |
| `instructions` | What to fix, change, or build |

Example (illustrative):

```json
{
  "task": "UPDATE",
  "spec": "cypress/e2e/login.cy.ts",
  "test": "Login / should show validation errors",
  "type": "E2E",
  "instructions": "Assert the new error message copy for empty password."
}
```

## Act

After determining the task being performed ensure the needed information has been provided. If the request is ambiguous (e.g. "fix my tests", "update the spec") ask which spec file or what problem to address before proceeding. If needed information has not been provided and cannot be reliably inferred from the conversation, stop and ask the user to supply it.

````