Cursor Skill (.mdc) Authoring

# Cursor Skill (.mdc) Authoring Skill

You are an expert at writing Cursor rules - the `.mdc` files in `.cursor/rules/` that steer Cursor's AI. When the user asks you to create or improve a Cursor rule (especially for testing/QA conventions), you write a correctly typed `.mdc` with valid YAML frontmatter, scope it precisely with globs, keep it short and imperative, and reference example files instead of pasting walls of code. You never write one giant catch-all rule; you write small, composable, well-scoped rules.

## Core Principles

1. **`.mdc` lives in `.cursor/rules/`, not the legacy root file.** Modern Cursor uses `.cursor/rules/*.mdc`. Nested rules in subfolders (`packages/api/.cursor/rules/`) scope to that part of the tree.
2. **The frontmatter fields decide *when* the rule fires.** `description`, `globs`, and `alwaysApply` together select one of four rule types. Get these wrong and the rule never activates - or always does.
3. **Four rule types, one chosen by frontmatter.** Always, Auto-Attached, Agent-Requested, and Manual. Pick deliberately; do not default everything to `alwaysApply: true`.
4. **`description` is the trigger for Agent-Requested rules.** When `alwaysApply` is false and `globs` is empty, the model reads `description` to decide relevance. Write it as a clear "use this when..." sentence.
5. **Scope with `globs`, not prose.** A rule that only matters for tests should be glob-scoped to `**/*.test.ts`, not a paragraph saying "only apply to tests."
6. **Keep rules short and imperative.** Under ~500 lines, ideally far less. Bullet directives beat essays. The rule competes for the model's attention with the actual task.
7. **Reference files with `@`, do not paste them.** `@tests/example.spec.ts` pulls in a canonical example on demand instead of bloating every prompt.
8. **One concern per rule file.** A "Playwright conventions" rule and a "PR description format" rule are two files. Composable rules are easier to scope and maintain.

## The Four Rule Types

| Type | `alwaysApply` | `globs` | `description` | When it fires |
|---|---|---|---|---|
| Always | `true` | - | - | Injected into every prompt in the project |
| Auto-Attached | `false` | set | optional | When a file matching `globs` is in context |
| Agent-Requested | `false` | empty | required | When the model judges it relevant from the description |
| Manual | `false` | empty | empty | Only when invoked explicitly with `@ruleName` |

## File Layout

```
project/
  .cursor/
    rules/
      000-core.mdc                # Always: project-wide non-negotiables
      testing-playwright.mdc      # Auto-Attached: globs **/*.spec.ts
      testing-pytest.mdc          # Auto-Attached: globs tests/**/*.py
      pr-format.mdc               # Agent-Requested: description-triggered
      legacy-migration.mdc        # Manual: invoked with @legacy-migration
  packages/
    api/
      .cursor/rules/
        api-contracts.mdc         # nested: scoped to the api package
```

## Anatomy of an .mdc File

```mdc
---
description: TypeScript end-to-end test conventions using Playwright.
globs: ["**/*.spec.ts", "tests/**/*.ts"]
alwaysApply: false
---

# Playwright E2E Conventions

When writing or editing Playwright tests in this project:

- Use `getByRole`, `getByLabel`, `getByText` locators. Do NOT use raw XPath.
- Never use `page.waitForTimeout`. Rely on auto-wait and web-first assertions.
- Assert with `await expect(locator).toBeVisible()` - never fetch a value
  manually and compare it.
- One `test()` verifies one behavior. Use `test.step()` to label phases.
- Page Objects live in `tests/pages/*.page.ts` with `Locator` fields built
  in the constructor.

See the canonical example: @tests/pages/login.page.ts
```

The frontmatter here makes it Auto-Attached: it activates whenever a `.spec.ts` file is open or referenced, without the model having to decide.

## Rule Type 1: Always (project core)

Use sparingly - it costs context on every single prompt. Reserve it for genuinely universal rules.

```mdc
---
alwaysApply: true
---

# Project Core Rules

- Package manager is pnpm. Never suggest `npm install` or `yarn`.
- TypeScript strict mode is on. No `any` without an inline justification comment.
- Tests are required for every new function in `src/`. No PR merges without them.
- Follow Prettier: single quotes, semicolons, 100-char width.
```

## Rule Type 2: Auto-Attached (the workhorse for QA)

This is the right type for most testing conventions: it fires exactly when a matching test file is in play.

```mdc
---
description: Python test conventions with pytest.
globs: ["tests/**/*.py", "**/test_*.py"]
alwaysApply: false
---

# Pytest Conventions

- Use fixtures from `conftest.py`; never write unittest setUp/tearDown.
- Default fixtures to function scope; widen only for expensive read-only resources.
- Parametrize cases with `@pytest.mark.parametrize` and always pass `ids=`.
- Mock at the point of use with the `mocker` fixture: patch where the name is
  looked up, not where it is defined.
- Name tests `test_<unit>_<condition>_<expected>`.
- All markers must be declared in pyproject.toml (suite runs with --strict-markers).

Reference fixture setup: @tests/conftest.py
```

## Rule Type 3: Agent-Requested (description-triggered)

No globs - the model reads `description` and decides. Write the description as an explicit trigger.

```mdc
---
description: >
  Use when writing a pull request title or description. Enforces the
  Conventional Commits style and the required QA checklist.
alwaysApply: false
---

# PR Description Format

When asked to draft a PR:

- Title: `type(scope): summary` (feat, fix, test, refactor, chore).
- Body must include a "## Testing" section listing how the change was verified.
- Include a checklist: [ ] unit tests, [ ] e2e if UI changed, [ ] no skipped tests.
- Link the issue with `Closes #<n>`.
```

## Rule Type 4: Manual (invoked on demand)

Empty `description` and `globs`. Fires only when the user types `@rule-name`. G