Cursor Skills for QA can turn a repeated test-review prompt into a version-controlled workflow. Instead of reminding an agent to inspect selectors, synchronization, assertions, test data, and regression risk every time, you can package that guidance in a SKILL.md file. This tutorial builds a small review skill, invokes it against a test automation diff, and validates every useful finding with deterministic evidence.

What Cursor Agent Skills provide

Cursor’s official documentation describes an Agent Skill as a portable package of domain knowledge and workflow instructions. Cursor discovers skills from project and user directories, including .cursor/skills/ and .agents/skills/. A skill lives in its own folder and requires a SKILL.md file with name and description frontmatter.

A skill may also contain scripts/, references/, and assets/. That structure is useful for QA because the concise review workflow can stay in SKILL.md, while a longer selector policy or defect template loads only when needed. Skills can be selected automatically when their description matches the task or invoked manually from Agent chat. The paths field can restrict a skill to test files, and disable-model-invocation can make it manual-only.

Choose a bounded QA review goal

Do not begin with a vague instruction such as “review all tests.” Choose a repeatable decision that has observable evidence. Our example reviews a Playwright diff for four risks:

  • brittle selectors that depend on layout or generated classes;
  • fixed delays or synchronization that does not wait for a user-visible condition;
  • weak assertions that only prove an element exists;
  • missing negative, boundary, or cleanup coverage.

The skill will produce findings, but it will not silently change files or declare a build safe. Each finding must cite the relevant file and explain a focused command or reproduction step. This boundary keeps the AI output useful without confusing a plausible suggestion with proof.

Build Cursor Skills for QA step by step

1. Create the project skill folder

At the repository root, create this structure:

.cursor/
  skills/
    qa-test-review/
      SKILL.md
      references/
        review-checklist.md

Project-level placement makes the workflow version-controlled and reviewable with the test suite. In a monorepo, a nested skill directory can scope the skill to the package beneath it. You can also use the paths field when file-pattern scoping is clearer.

2. Add a focused SKILL.md

Use a lowercase, hyphenated name that matches the parent folder. Give the description enough detail for the agent to know when the skill applies.

Starter snippet: reusable QA review skill

---
name: qa-test-review
description: Review test automation diffs for selector, synchronization, assertion, test-data, and regression risks. Use for Playwright test changes before a pull request.
paths:
  - "tests/**/*.spec.ts"
  - "pages/**/*.ts"
---

# QA test review

1. Inspect only the requested diff and nearby production contracts.
2. Report selector, synchronization, assertion, isolation, and cleanup risks.
3. For each finding, cite the file and explain the failure it could hide.
4. Suggest the smallest focused test command that can validate the finding.
5. Do not edit files unless the user explicitly asks.
6. Separate confirmed evidence from hypotheses.
7. End with: findings, validation commands, and residual risks.

Read references/review-checklist.md when detailed criteria are needed.

Keep the main file short and actionable. Put organization-specific examples in the reference file: preferred role-based selectors, approved test-data factories, retry policy, fixture cleanup rules, and the exact commands used in CI. Avoid copying a large style guide that will become stale.

3. Decide automatic or manual invocation

The example allows Cursor to select the skill when a matching test file and request are in context. If your team requires an explicit review action, add disable-model-invocation: true to the frontmatter. Testers can then type / in Agent chat and choose the skill by name. Manual invocation is a good fit when the workflow has a cost, performs scripts, or represents a formal pre-PR gate.

4. Run it against a small diff

Start with one changed spec and its related page object. A copy-ready request is:

Use the qa-test-review skill on the current diff in tests/checkout.spec.ts and pages/checkout-page.ts. Do not edit files. Rank findings by user impact, cite the exact evidence, and give one focused validation command per finding.

Review the plan and ensure the agent stays inside the requested files. A useful result connects a code pattern to a credible failure mode. “This locator is bad” is weak. “This generated CSS class changes between builds; prefer the stable accessible name already exposed by the button” is testable.

5. Validate findings independently

Run the focused test command yourself, inspect the trace or report, and reproduce any claimed failure. For example:

npx playwright test tests/checkout.spec.ts --project=chromium --trace=on

If a suggested locator or assertion changes, rerun the affected test repeatedly and include the relevant smoke suite. Inspect the final diff before committing. Cursor’s own best-practices guidance emphasizes careful review of AI-generated changes and verifiable goals; passing deterministic checks, not confident wording, is the acceptance signal.

Example review checklist

  • Selectors: Prefer stable user-facing roles, labels, or explicit test IDs over DOM position and generated classes.
  • Synchronization: Wait for observable application state, network completion, or a Playwright assertion rather than an arbitrary delay.
  • Assertions: Verify the business outcome, not only visibility or HTTP success.
  • Isolation: Confirm tests do not depend on execution order, shared accounts, or leftover data.
  • Evidence: Preserve the failing command, environment, trace, screenshot, and relevant log excerpt.
  • Scope: Note nearby paths that were not tested and any residual release risk.

Common mistakes to avoid

Making the skill too broad: a giant QA handbook is difficult to trigger correctly and easy to age. Split API, UI, accessibility, and performance reviews into focused skills.

Letting advice become an automatic verdict: a skill standardizes analysis; it does not make the model deterministic. Require reproduction and human review.

Embedding secrets or production data: keep credentials, customer records, and sensitive traces out of instructions and examples. Use sanitized fixtures and approved environments.

Skipping version control: review changes to the skill like code. A small instruction change can alter what the agent flags or ignores.

Ignoring false negatives: no findings does not mean no defects. Continue to run regression, accessibility, security, and performance checks appropriate to the change.

Screenshot checklist

  1. The .cursor/skills/qa-test-review/ folder in the project tree.
  2. The SKILL.md frontmatter and review steps open in the editor.
  3. The skill visible in Cursor’s slash menu or Customize view.
  4. The bounded review prompt beside the selected test diff.
  5. A finding that cites a file and proposes a focused validation command.
  6. The Playwright terminal result and trace proving or disproving the finding.
  7. The final reviewed diff with no unrelated changes.

Best practices for team adoption

Pilot the skill on a handful of known pull requests, including one clean change and several changes with seeded review risks. Track useful findings, false positives, missed issues, and review time. Refine instructions with concrete examples, but keep linters and test runners responsible for machine-checkable rules. Assign ownership for quarterly review or whenever test architecture changes.

Use a pull request to modify the skill, and ask reviewers to inspect both the wording and its observed output on a representative diff. The best Cursor Skills for QA workflow is transparent: teammates can see what guidance ran, what evidence supported each finding, and which checks still require human judgment.

FAQ

Are Cursor Agent Skills the same as rules?

No. Cursor describes rules as persistent project context, while skills package dynamic capabilities and workflows that load when relevant or are invoked manually.

Can a skill run scripts?

Yes. Official documentation allows an optional scripts/ directory. Treat scripts as code: review them, constrain permissions, handle failures, and avoid secrets.

Should the skill edit tests automatically?

For a review workflow, start read-only. Ask for a separate, explicit edit after validating the finding and preserve human review of the final diff.

How do I prevent automatic invocation?

Add disable-model-invocation: true to the skill frontmatter, then invoke it explicitly from Agent chat.

Does a clean skill report prove the test is safe?

No. AI review can miss defects. Run deterministic tests, inspect evidence, and retain normal security, accessibility, regression, and merge gates.

Conclusion

Cursor Skills for QA make a repeated review process portable, scoped, and version-controlled. Keep the workflow narrow, require evidence, validate every material finding with focused tests, and let a human decide what reaches the pull request. That combination gives QA engineers a faster review loop without weakening the release gate.

References