From 147166d68dcc3d63b767996dfbce781fa9c3759c Mon Sep 17 00:00:00 2001 From: Mike Plummer Date: Thu, 30 Apr 2026 08:51:36 -0500 Subject: [PATCH 1/7] feat: Establish plugin metadata --- .claude-plugin/marketplace.json | 23 +++++++++++++++++++++++ .claude-plugin/plugin.json | 24 ++++++++++++++++++++++++ .cursor-plugin/plugin.json | 25 +++++++++++++++++++++++++ .prettierrc.json | 4 ++++ mcp/.mcp.claude.json | 10 ++++++++++ mcp/.mcp.cursor.json | 10 ++++++++++ mcp/README.md | 3 +++ 7 files changed, 99 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json create mode 100644 .cursor-plugin/plugin.json create mode 100644 .prettierrc.json create mode 100644 mcp/.mcp.claude.json create mode 100644 mcp/.mcp.cursor.json create mode 100644 mcp/README.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..6a048bc --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", + "name": "cypress", + "description": "Cypress plugin marketplace for Claude Code", + "owner": { + "name": "Cypress.io", + "email": "support@cypress.io" + }, + "plugins": [ + { + "name": "cypress", + "description": "Create, update, and fix Cypress tests. Connect to Cypress Cloud to see test results and use data to manage your test suite.", + "version": "1.0.0", + "author": { + "name": "Cypress.io", + "email": "support@cypress.io" + }, + "source": "./", + "category": "productivity", + "homepage": "https://github.com/cypress-io/ai-toolkit" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..7c1c34b --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,24 @@ +{ + "name": "cypress", + "displayName": "Cypress", + "version": "1.0.0", + "description": "Create, update, and fix Cypress tests. Connect to Cypress Cloud to see test results and use data to manage your test suite.", + "author": { + "name": "Cypress.io", + "email": "support@cypress.io" + }, + "license": "MIT", + "keywords": [ + "cursor", + "plugin", + "cypress", + "ai", + "testing", + "automation", + "qa" + ], + "repository": "https://github.com/cypress-io/ai-toolkit", + "homepage": "https://www.cypress.io", + "skills": "./skills/", + "mcp": "./mcp/.mcp.claude.json" +} diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json new file mode 100644 index 0000000..ce89a21 --- /dev/null +++ b/.cursor-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "cypress", + "displayName": "Cypress", + "version": "1.0.0", + "description": "Create, update, and fix Cypress tests. Connect to Cypress Cloud to see test results and use data to manage your test suite.", + "author": { + "name": "Cypress.io", + "email": "support@cypress.io" + }, + "license": "MIT", + "keywords": [ + "cursor", + "plugin", + "cypress", + "ai", + "testing", + "automation", + "qa" + ], + "logo": "assets/cypress-logotype-dark.svg", + "repository": "https://github.com/cypress-io/ai-toolkit", + "homepage": "https://www.cypress.io", + "skills": "./skills/", + "mcpServers": "./mcp/.mcp.cursor.json" +} diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..222861c --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,4 @@ +{ + "tabWidth": 2, + "useTabs": false +} diff --git a/mcp/.mcp.claude.json b/mcp/.mcp.claude.json new file mode 100644 index 0000000..dc0fe60 --- /dev/null +++ b/mcp/.mcp.claude.json @@ -0,0 +1,10 @@ +{ + "mcpServers": { + "cypress": { + "url": "https://mcp.cypress.io/mcp", + "headers": { + "Authorization": "Bearer ${CYPRESS_MCP_TOKEN}" + } + } + } +} \ No newline at end of file diff --git a/mcp/.mcp.cursor.json b/mcp/.mcp.cursor.json new file mode 100644 index 0000000..cbf0b3b --- /dev/null +++ b/mcp/.mcp.cursor.json @@ -0,0 +1,10 @@ +{ + "mcpServers": { + "cypress-cloud": { + "url": "https://mcp.cypress.io/mcp", + "headers": { + "Authorization": "Bearer ${env:CYPRESS_MCP_TOKEN}" + } + } + } +} \ No newline at end of file diff --git a/mcp/README.md b/mcp/README.md new file mode 100644 index 0000000..1b1b780 --- /dev/null +++ b/mcp/README.md @@ -0,0 +1,3 @@ +# Model Context Protocol Definitions + +This directory contains the MCP configuration for each agent type - unfortunately different agents use different syntax for certain things like environment variable interpolation, so it ends up being a bit duplicative. From 27620cc244fc3eb92f56ee7a43be99e2de03bffe Mon Sep 17 00:00:00 2001 From: Mike Plummer Date: Thu, 30 Apr 2026 09:59:14 -0500 Subject: [PATCH 2/7] fix claude mcp config --- .claude-plugin/plugin.json | 2 +- mcp/.mcp.claude.json | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 7c1c34b..b173c57 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -20,5 +20,5 @@ "repository": "https://github.com/cypress-io/ai-toolkit", "homepage": "https://www.cypress.io", "skills": "./skills/", - "mcp": "./mcp/.mcp.claude.json" + "mcpServers": "./mcp/.mcp.claude.json" } diff --git a/mcp/.mcp.claude.json b/mcp/.mcp.claude.json index dc0fe60..4ec2cf5 100644 --- a/mcp/.mcp.claude.json +++ b/mcp/.mcp.claude.json @@ -1,6 +1,7 @@ { "mcpServers": { - "cypress": { + "cypress-cloud": { + "type": "http", "url": "https://mcp.cypress.io/mcp", "headers": { "Authorization": "Bearer ${CYPRESS_MCP_TOKEN}" From a35eb13c656389c962c281275d48b6a637fac644 Mon Sep 17 00:00:00 2001 From: Mike Plummer Date: Thu, 30 Apr 2026 10:18:26 -0500 Subject: [PATCH 3/7] Update README.md --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 77ce240..d53ad5c 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,14 @@ The community will help shape what gets prioritized. If you're already unlocking ## Getting started +The Cypress AI toolkit is published as a plugin for both Claude and Cursor. This is the easiest way to install and configure the various capabilities in this package and also enables an auto-update capability. + +_Note: Listings in the Claude and Cursor official plugin marketplaces are currently pending. This README will be updated once they are available. Until then, this repository can be cloned and installed as a local plugin in your agent of choice._ + +### Manual Installation + +If you're using another agent or prefer to pick-and-choose you can pick the portions of this repository you want. + 1. Install the skills using the [`skills`](https://skills.sh/) package: ```sh @@ -52,6 +60,8 @@ The community will help shape what gets prioritized. If you're already unlocking For manual installation, example prompts, and more, see the [skills documentation](./skills/README.md) or the [Cypress AI Skills docs](https://docs.cypress.io/app/tooling/ai-skills). +3. The Cypress Cloud MCP configuration can be copied into your agent, or you can follow the [configuration instructions here](https://docs.cypress.io/cloud/integrations/cloud-mcp). + ## Who this is for This toolkit is for Cypress developers who use AI coding tools and want consistent, reliable output — not just code that runs. From a07aaaee7798043cf0927371f1aa6aa234d3c390 Mon Sep 17 00:00:00 2001 From: Mike Plummer Date: Thu, 30 Apr 2026 10:26:21 -0500 Subject: [PATCH 4/7] Update with review submission results --- .claude-plugin/marketplace.json | 9 +++++---- .claude-plugin/plugin.json | 4 ++-- .cursor-plugin/marketplace.json | 15 +++++++++++++++ .cursor-plugin/plugin.json | 4 ++-- 4 files changed, 24 insertions(+), 8 deletions(-) create mode 100644 .cursor-plugin/marketplace.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6a048bc..fb31809 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -4,7 +4,8 @@ "description": "Cypress plugin marketplace for Claude Code", "owner": { "name": "Cypress.io", - "email": "support@cypress.io" + "email": "support@cypress.io", + "url": "https://www.cypress.io" }, "plugins": [ { @@ -13,11 +14,11 @@ "version": "1.0.0", "author": { "name": "Cypress.io", - "email": "support@cypress.io" + "email": "support@cypress.io", + "url": "https://www.cypress.io" }, "source": "./", - "category": "productivity", - "homepage": "https://github.com/cypress-io/ai-toolkit" + "category": "productivity" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b173c57..26edd33 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -5,7 +5,8 @@ "description": "Create, update, and fix Cypress tests. Connect to Cypress Cloud to see test results and use data to manage your test suite.", "author": { "name": "Cypress.io", - "email": "support@cypress.io" + "email": "support@cypress.io", + "url": "https://www.cypress.io" }, "license": "MIT", "keywords": [ @@ -18,7 +19,6 @@ "qa" ], "repository": "https://github.com/cypress-io/ai-toolkit", - "homepage": "https://www.cypress.io", "skills": "./skills/", "mcpServers": "./mcp/.mcp.claude.json" } diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json new file mode 100644 index 0000000..04c62e3 --- /dev/null +++ b/.cursor-plugin/marketplace.json @@ -0,0 +1,15 @@ +{ + "name": "cypress", + "owner": { + "name": "Cypress.io", + "email": "support@cypress.io", + "url": "https://www.cypress.io" + }, + "plugins": [ + { + "name": "cypress", + "source": "./", + "description": "Create, update, and fix Cypress tests. Connect to Cypress Cloud to see test results and use data to manage your test suite." + } + ] +} diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index ce89a21..01591d8 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -5,7 +5,8 @@ "description": "Create, update, and fix Cypress tests. Connect to Cypress Cloud to see test results and use data to manage your test suite.", "author": { "name": "Cypress.io", - "email": "support@cypress.io" + "email": "support@cypress.io", + "url": "https://www.cypress.io" }, "license": "MIT", "keywords": [ @@ -19,7 +20,6 @@ ], "logo": "assets/cypress-logotype-dark.svg", "repository": "https://github.com/cypress-io/ai-toolkit", - "homepage": "https://www.cypress.io", "skills": "./skills/", "mcpServers": "./mcp/.mcp.cursor.json" } From 67fc02fb8bad3c975250c6368280fffb49168d2a Mon Sep 17 00:00:00 2001 From: Mike Plummer Date: Thu, 30 Apr 2026 10:39:51 -0500 Subject: [PATCH 5/7] remove incorrect keyword --- .claude-plugin/plugin.json | 1 - .cursor-plugin/plugin.json | 1 - 2 files changed, 2 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 26edd33..c9b568e 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -10,7 +10,6 @@ }, "license": "MIT", "keywords": [ - "cursor", "plugin", "cypress", "ai", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 01591d8..c4a149f 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -10,7 +10,6 @@ }, "license": "MIT", "keywords": [ - "cursor", "plugin", "cypress", "ai", From 879ecc4b27a123eb29a3234ca8b288296defdb6f Mon Sep 17 00:00:00 2001 From: Mike Plummer Date: Thu, 30 Apr 2026 14:22:14 -0500 Subject: [PATCH 6/7] feat: New `cypress-docs` skill --- README.md | 3 +- skills/README.md | 11 + skills/cypress-author/SKILL.md | 2 +- .../documentation/documentation-rules.md | 2 +- skills/cypress-docs/SKILL.md | 220 ++++++++++++++++++ skills/cypress-explain/SKILL.md | 2 +- .../documentation/documentation-rules.md | 2 +- 7 files changed, 237 insertions(+), 5 deletions(-) create mode 100644 skills/cypress-docs/SKILL.md diff --git a/README.md b/README.md index d53ad5c..d9e9c0b 100644 --- a/README.md +++ b/README.md @@ -25,10 +25,11 @@ The Cypress AI Toolkit gives your AI tools the Cypress-specific context they nee Skills are instruction sets your AI tool loads to apply Cypress-specific knowledge when generating or reviewing test code. They fill the gap between what an AI learned during training and what current, well-written Cypress tests actually look like. -Two skills are available now: +Three skills are available now: - **[`cypress-author`](./skills/README.md#cypress-author)** — Improves how AI tools create, update, and fix Cypress tests. Use it when you're writing new tests or fixing broken ones. - **[`cypress-explain`](./skills/README.md#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. +- **[`cypress-docs`](./skills/README.md#cypress-docs)** - Helps your agent research and retrieve information about Cypress more efficiently and reliably. Skills work with any AI tool that accepts custom instructions, including Claude, Cursor, and GitHub Copilot. diff --git a/skills/README.md b/skills/README.md index de2f6d6..38a39f3 100644 --- a/skills/README.md +++ b/skills/README.md @@ -22,6 +22,7 @@ Or install a specific skill with: ```sh 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 ``` See [skills.sh](https://skills.sh/) for full documentation, including how to update and remove skills. Note that the update check in the `skills` package only tracks project-level installs, not global ones. @@ -63,6 +64,16 @@ This skill translates Cypress commands and patterns into plain language, surface > How does cy.intercept() work, and when should I use cy.wait('@alias') with it? +### [`cypress-docs`](./cypress-docs) +Helps your agent use Cypress documentation more effectively and reliably by using LLM-optimized resources and supplying guidance on how to parse and extract information while grounding answers in verifiable information. + +This skill is meant to help inform and support other Cypress skills. + +#### Example + +**Define a Cypress API:** + +> Define the Cypress `cy.prompt` API ## Troubleshooting diff --git a/skills/cypress-author/SKILL.md b/skills/cypress-author/SKILL.md index b1c16ff..c4296fd 100644 --- a/skills/cypress-author/SKILL.md +++ b/skills/cypress-author/SKILL.md @@ -5,7 +5,7 @@ model: inherit background: false allowed-tools: Read, Edit metadata: - version: 1.0.0 + version: 1.0.1 --- # Cypress Author diff --git a/skills/cypress-author/references/documentation/documentation-rules.md b/skills/cypress-author/references/documentation/documentation-rules.md index 1859b48..5dcb6a5 100644 --- a/skills/cypress-author/references/documentation/documentation-rules.md +++ b/skills/cypress-author/references/documentation/documentation-rules.md @@ -1,7 +1,7 @@ # Cypress Documentation Always prefer authoritative Cypress sources over third-party content. These include: - - [Cypress Docs](https://on.cypress.io/docs) + - [Cypress Docs](https://on.cypress.io/docs) - 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. diff --git a/skills/cypress-docs/SKILL.md b/skills/cypress-docs/SKILL.md new file mode 100644 index 0000000..ca69f12 --- /dev/null +++ b/skills/cypress-docs/SKILL.md @@ -0,0 +1,220 @@ +--- +name: cypress-docs +description: Search and extract Cypress information from official documentation (docs.cypress.io, cypress.io); prefer LLM markdown under /llm/* and refuse unverified API or behavior claims. +model: inherit +background: false +metadata: + version: 1.0.0 +--- + +# Cypress Documentation + +## Purpose +Enable the agent to retrieve accurate, up-to-date, and verifiable information about the Cypress testing framework by prioritizing official documentation and structured sources. + +## When to use + +Apply this skill whenever the task depends on **finding, reading, or quoting Cypress documentation** rather than general testing intuition: + +- **Look up facts**: commands, APIs, assertions, lifecycle hooks, configuration options, environment variables, CLI flags, plugins, or TypeScript types as documented by Cypress. +- **Confirm behavior**: how something works in a given Cypress version, E2E vs component testing differences, browser support, or networking/cy.intercept semantics. +- **Before asserting “Cypress can/cannot…”**: search docs first; do not rely on memory for exact signatures, defaults, or deprecated APIs. +- **Extract structured content**: follow the LLM-optimized docs strategy below (`llms.txt`, `/llm/*`) when fetching or summarizing doc pages. +- **Ground answers for others**: when explaining Cypress to a user, writing examples, or reviewing code where correctness must match official docs. + +If the user only needs **writing or fixing tests** without a documentation lookup, prefer `cypress-author`; if they only need **test explanation** without fetching docs, prefer `cypress-explain`. Use **this** skill when official documentation is the source of truth. + +## Source Prioritization + +### Primary Sources (ALWAYS search first) +- https://docs.cypress.io +- https://www.cypress.io + +## 🤖 LLM-Optimized Docs Strategy + +When accessing `docs.cypress.io`: + +1. Fetch `/llms.txt` + +2. Parse it to discover: + - LLM-friendly documentation paths + - Structured content endpoints + +3. Prefer content under `/llm/*`. Every path on the site has an optimized version hosted under `/llm` - for example, `https://docs.cypress.io/app/faq` is available at `https://docs.cypress.io/llm/markdown/app/faq.md`. + +4. Why: + - Markdown / JSON format + - Cleaner structure + - Less noise than HTML + +5. Fallback: + - If `/llm/*` is incomplete, use standard docs pages + +## Critical Rules + +### Never Assume Missing Features +- NEVER assume Cypress does not support a feature +- ALWAYS search before concluding +- Retry with alternate terminology if needed + +### Anti-Hallucination Guard + +If documentation cannot verify a claim: + +- Say: "I could not verify this in Cypress docs" +- Provide closest supported alternative (if available) +- DO NOT invent APIs or behavior + +## Docs Site Map (Mental Model) + + docs.cypress.io/ + ├── /app/ + │ ├── getting-started/ + │ ├── core-concepts/ + │ ├── end-to-end-testing/ + │ ├── component-testing/ + │ ├── api/ + │ │ ├── commands/ + │ │ ├── assertions/ + │ │ └── utilities/ + │ ├── guides/ + │ ├── plugins/ + │ ├── configuration/ + │ ├── cli/ + │ └── references/ + │ ├── error-messages + │ ├── configuration + │ └── environment-variables + │ + ├── /examples/ + ├── /faq/ + ├── /changelog/ + │ + └── /llm/ ← PRIMARY TARGET + ├── /markdown/api/ + ├── /markdown/guides/ + ├── /markdown/concepts/ + └── /markdown/config/ + +## Search Strategy + +### 1. Classify the Query + +| Query Type | Search Location | +|------------------|------------------------------| +| How do I... | /guides/, /core-concepts/ | +| What is... | /core-concepts/ | +| API / Commands | /api/commands/ | +| Assertions | /api/assertions/ | +| Config issues | /configuration/ | +| CI/CD | /guides/ci-cd/ | +| Errors | /references/error-messages/ | + +### 2. Search Flow + +1. `/llm/*` (via `/llms.txt`) +2. Standard docs pages +3. `/changelog/` +4. `cypress.io` (blog, updates) + +### 3. Error-Aware Routing + +If the query includes: +- Error messages +- Stack traces + +Then: +1. Search `/references/error-messages` +2. Expand to guides and API docs + +## Structured Extraction Rules + +### Commands +- Syntax +- Required arguments +- Optional options +- Return behavior +- Example usage + +### Concepts +- Definition +- Key rules +- Common pitfalls +- Example + +### Configuration +- Option name +- Type +- Default value +- Example + +## Version Awareness + +- Detect Cypress version if provided +- If NOT provided: assume latest stable version +- If behavior differs by version: + - Explicitly call it out + +## Response Style Guidelines + +- Prefer official examples +- Provide working code snippets +- Keep answers concise but complete +- Avoid speculation + +## Caching Strategy (Optional) + +Cache frequently used topics: +- cy.visit +- cy.get +- cy.intercept +- authentication patterns +- common configuration + +## Confidence Annotation + +Internally assess confidence: + +- High → Direct match in official docs +- Medium → Inferred from multiple sources +- Low → Unclear or edge case + +If LOW: +- Clearly communicate uncertainty + +## LLM Path Auto-Discovery + +- Always parse `/llms.txt` +- Dynamically adapt to: + - New `/llm/*` paths + - Updated documentation formats + +## Safety Rules + +- NEVER invent Cypress APIs +- NEVER guess syntax +- ALWAYS verify behavior +- Prefer "unknown" over incorrect + +## Example Behavior + +User: "How do I mock API requests in Cypress?" + +Agent should: +1. Classify → API / network +2. Search `/llm/markdown/api/` and `/llm/markdown/guides/` +3. Identify `cy.intercept` +4. Extract structured details +5. Return: + - Explanation + - Syntax + - Example + - Notes + +## Summary + +This skill ensures: +- Accurate answers from official sources +- Reduced hallucination +- Structured, high-quality outputs +- Adaptability to evolving Cypress docs diff --git a/skills/cypress-explain/SKILL.md b/skills/cypress-explain/SKILL.md index 60dbd4a..7fe2b32 100644 --- a/skills/cypress-explain/SKILL.md +++ b/skills/cypress-explain/SKILL.md @@ -5,7 +5,7 @@ model: inherit background: false allowed-tools: Read metadata: - version: 1.0.0 + version: 1.0.1 --- # Cypress Explain diff --git a/skills/cypress-explain/references/documentation/documentation-rules.md b/skills/cypress-explain/references/documentation/documentation-rules.md index 07dc553..aee6e63 100644 --- a/skills/cypress-explain/references/documentation/documentation-rules.md +++ b/skills/cypress-explain/references/documentation/documentation-rules.md @@ -1,5 +1,5 @@ # Cypress Documentation -Always prefer [authoritative Cypress sources](https://on.cypress.io/docs) over third-party content. +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. From 6c2b5c93eabb457434b0f849321ba952ff18af3b Mon Sep 17 00:00:00 2001 From: Mike Plummer Date: Thu, 30 Apr 2026 14:22:27 -0500 Subject: [PATCH 7/7] Revert "feat: New `cypress-docs` skill" This reverts commit 879ecc4b27a123eb29a3234ca8b288296defdb6f. --- README.md | 3 +- skills/README.md | 11 - skills/cypress-author/SKILL.md | 2 +- .../documentation/documentation-rules.md | 2 +- skills/cypress-docs/SKILL.md | 220 ------------------ skills/cypress-explain/SKILL.md | 2 +- .../documentation/documentation-rules.md | 2 +- 7 files changed, 5 insertions(+), 237 deletions(-) delete mode 100644 skills/cypress-docs/SKILL.md diff --git a/README.md b/README.md index d9e9c0b..d53ad5c 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,10 @@ The Cypress AI Toolkit gives your AI tools the Cypress-specific context they nee Skills are instruction sets your AI tool loads to apply Cypress-specific knowledge when generating or reviewing test code. They fill the gap between what an AI learned during training and what current, well-written Cypress tests actually look like. -Three skills are available now: +Two skills are available now: - **[`cypress-author`](./skills/README.md#cypress-author)** — Improves how AI tools create, update, and fix Cypress tests. Use it when you're writing new tests or fixing broken ones. - **[`cypress-explain`](./skills/README.md#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. -- **[`cypress-docs`](./skills/README.md#cypress-docs)** - Helps your agent research and retrieve information about Cypress more efficiently and reliably. Skills work with any AI tool that accepts custom instructions, including Claude, Cursor, and GitHub Copilot. diff --git a/skills/README.md b/skills/README.md index 38a39f3..de2f6d6 100644 --- a/skills/README.md +++ b/skills/README.md @@ -22,7 +22,6 @@ Or install a specific skill with: ```sh 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 ``` See [skills.sh](https://skills.sh/) for full documentation, including how to update and remove skills. Note that the update check in the `skills` package only tracks project-level installs, not global ones. @@ -64,16 +63,6 @@ This skill translates Cypress commands and patterns into plain language, surface > How does cy.intercept() work, and when should I use cy.wait('@alias') with it? -### [`cypress-docs`](./cypress-docs) -Helps your agent use Cypress documentation more effectively and reliably by using LLM-optimized resources and supplying guidance on how to parse and extract information while grounding answers in verifiable information. - -This skill is meant to help inform and support other Cypress skills. - -#### Example - -**Define a Cypress API:** - -> Define the Cypress `cy.prompt` API ## Troubleshooting diff --git a/skills/cypress-author/SKILL.md b/skills/cypress-author/SKILL.md index c4296fd..b1c16ff 100644 --- a/skills/cypress-author/SKILL.md +++ b/skills/cypress-author/SKILL.md @@ -5,7 +5,7 @@ model: inherit background: false allowed-tools: Read, Edit metadata: - version: 1.0.1 + version: 1.0.0 --- # Cypress Author diff --git a/skills/cypress-author/references/documentation/documentation-rules.md b/skills/cypress-author/references/documentation/documentation-rules.md index 5dcb6a5..1859b48 100644 --- a/skills/cypress-author/references/documentation/documentation-rules.md +++ b/skills/cypress-author/references/documentation/documentation-rules.md @@ -1,7 +1,7 @@ # Cypress Documentation Always prefer authoritative Cypress sources over third-party content. These include: - - [Cypress Docs](https://on.cypress.io/docs) - review that site's `/llms.txt` file for LLM-specific guidance + - [Cypress Docs](https://on.cypress.io/docs) - The Cypress CLI (`npx cypress --help`) Before assuming that Cypress does not support a feature, behavior, or command perform a search of authoritative sources. diff --git a/skills/cypress-docs/SKILL.md b/skills/cypress-docs/SKILL.md deleted file mode 100644 index ca69f12..0000000 --- a/skills/cypress-docs/SKILL.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -name: cypress-docs -description: Search and extract Cypress information from official documentation (docs.cypress.io, cypress.io); prefer LLM markdown under /llm/* and refuse unverified API or behavior claims. -model: inherit -background: false -metadata: - version: 1.0.0 ---- - -# Cypress Documentation - -## Purpose -Enable the agent to retrieve accurate, up-to-date, and verifiable information about the Cypress testing framework by prioritizing official documentation and structured sources. - -## When to use - -Apply this skill whenever the task depends on **finding, reading, or quoting Cypress documentation** rather than general testing intuition: - -- **Look up facts**: commands, APIs, assertions, lifecycle hooks, configuration options, environment variables, CLI flags, plugins, or TypeScript types as documented by Cypress. -- **Confirm behavior**: how something works in a given Cypress version, E2E vs component testing differences, browser support, or networking/cy.intercept semantics. -- **Before asserting “Cypress can/cannot…”**: search docs first; do not rely on memory for exact signatures, defaults, or deprecated APIs. -- **Extract structured content**: follow the LLM-optimized docs strategy below (`llms.txt`, `/llm/*`) when fetching or summarizing doc pages. -- **Ground answers for others**: when explaining Cypress to a user, writing examples, or reviewing code where correctness must match official docs. - -If the user only needs **writing or fixing tests** without a documentation lookup, prefer `cypress-author`; if they only need **test explanation** without fetching docs, prefer `cypress-explain`. Use **this** skill when official documentation is the source of truth. - -## Source Prioritization - -### Primary Sources (ALWAYS search first) -- https://docs.cypress.io -- https://www.cypress.io - -## 🤖 LLM-Optimized Docs Strategy - -When accessing `docs.cypress.io`: - -1. Fetch `/llms.txt` - -2. Parse it to discover: - - LLM-friendly documentation paths - - Structured content endpoints - -3. Prefer content under `/llm/*`. Every path on the site has an optimized version hosted under `/llm` - for example, `https://docs.cypress.io/app/faq` is available at `https://docs.cypress.io/llm/markdown/app/faq.md`. - -4. Why: - - Markdown / JSON format - - Cleaner structure - - Less noise than HTML - -5. Fallback: - - If `/llm/*` is incomplete, use standard docs pages - -## Critical Rules - -### Never Assume Missing Features -- NEVER assume Cypress does not support a feature -- ALWAYS search before concluding -- Retry with alternate terminology if needed - -### Anti-Hallucination Guard - -If documentation cannot verify a claim: - -- Say: "I could not verify this in Cypress docs" -- Provide closest supported alternative (if available) -- DO NOT invent APIs or behavior - -## Docs Site Map (Mental Model) - - docs.cypress.io/ - ├── /app/ - │ ├── getting-started/ - │ ├── core-concepts/ - │ ├── end-to-end-testing/ - │ ├── component-testing/ - │ ├── api/ - │ │ ├── commands/ - │ │ ├── assertions/ - │ │ └── utilities/ - │ ├── guides/ - │ ├── plugins/ - │ ├── configuration/ - │ ├── cli/ - │ └── references/ - │ ├── error-messages - │ ├── configuration - │ └── environment-variables - │ - ├── /examples/ - ├── /faq/ - ├── /changelog/ - │ - └── /llm/ ← PRIMARY TARGET - ├── /markdown/api/ - ├── /markdown/guides/ - ├── /markdown/concepts/ - └── /markdown/config/ - -## Search Strategy - -### 1. Classify the Query - -| Query Type | Search Location | -|------------------|------------------------------| -| How do I... | /guides/, /core-concepts/ | -| What is... | /core-concepts/ | -| API / Commands | /api/commands/ | -| Assertions | /api/assertions/ | -| Config issues | /configuration/ | -| CI/CD | /guides/ci-cd/ | -| Errors | /references/error-messages/ | - -### 2. Search Flow - -1. `/llm/*` (via `/llms.txt`) -2. Standard docs pages -3. `/changelog/` -4. `cypress.io` (blog, updates) - -### 3. Error-Aware Routing - -If the query includes: -- Error messages -- Stack traces - -Then: -1. Search `/references/error-messages` -2. Expand to guides and API docs - -## Structured Extraction Rules - -### Commands -- Syntax -- Required arguments -- Optional options -- Return behavior -- Example usage - -### Concepts -- Definition -- Key rules -- Common pitfalls -- Example - -### Configuration -- Option name -- Type -- Default value -- Example - -## Version Awareness - -- Detect Cypress version if provided -- If NOT provided: assume latest stable version -- If behavior differs by version: - - Explicitly call it out - -## Response Style Guidelines - -- Prefer official examples -- Provide working code snippets -- Keep answers concise but complete -- Avoid speculation - -## Caching Strategy (Optional) - -Cache frequently used topics: -- cy.visit -- cy.get -- cy.intercept -- authentication patterns -- common configuration - -## Confidence Annotation - -Internally assess confidence: - -- High → Direct match in official docs -- Medium → Inferred from multiple sources -- Low → Unclear or edge case - -If LOW: -- Clearly communicate uncertainty - -## LLM Path Auto-Discovery - -- Always parse `/llms.txt` -- Dynamically adapt to: - - New `/llm/*` paths - - Updated documentation formats - -## Safety Rules - -- NEVER invent Cypress APIs -- NEVER guess syntax -- ALWAYS verify behavior -- Prefer "unknown" over incorrect - -## Example Behavior - -User: "How do I mock API requests in Cypress?" - -Agent should: -1. Classify → API / network -2. Search `/llm/markdown/api/` and `/llm/markdown/guides/` -3. Identify `cy.intercept` -4. Extract structured details -5. Return: - - Explanation - - Syntax - - Example - - Notes - -## Summary - -This skill ensures: -- Accurate answers from official sources -- Reduced hallucination -- Structured, high-quality outputs -- Adaptability to evolving Cypress docs diff --git a/skills/cypress-explain/SKILL.md b/skills/cypress-explain/SKILL.md index 7fe2b32..60dbd4a 100644 --- a/skills/cypress-explain/SKILL.md +++ b/skills/cypress-explain/SKILL.md @@ -5,7 +5,7 @@ model: inherit background: false allowed-tools: Read metadata: - version: 1.0.1 + version: 1.0.0 --- # Cypress Explain diff --git a/skills/cypress-explain/references/documentation/documentation-rules.md b/skills/cypress-explain/references/documentation/documentation-rules.md index aee6e63..07dc553 100644 --- a/skills/cypress-explain/references/documentation/documentation-rules.md +++ b/skills/cypress-explain/references/documentation/documentation-rules.md @@ -1,5 +1,5 @@ # 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 +Always prefer [authoritative Cypress sources](https://on.cypress.io/docs) over third-party content. Before assuming that Cypress does not support a feature, behavior, or command perform a search of authoritative sources.