How to Lint Your Cursor Rules in CI (So Broken Rules Don't Ship)

Source: Dev.to

Introduction

When you write a .mdc rule for Cursor, a small mistake—such as a missing alwaysApply field, malformed YAML front‑matter, or an incorrect glob pattern—can cause the rule to be silently ignored. The issue often isn’t discovered until you’re already in a session and the AI behaves unexpectedly.

cursor-lint is a lightweight tool that catches these problems before they waste your time, both locally and in CI.

What cursor-lint Checks

• Missing or malformed YAML front‑matter in .mdc files
• alwaysApply not set (agent mode won’t load the rule)
• Empty rule bodies (file exists but does nothing)
• Invalid glob patterns in the globs field
• Problems in .cursorrules files that Cursor itself doesn’t report

These failure modes have been verified: malformed YAML or missing front‑matter cause Cursor to load zero rules without any error.

Running cursor-lint Locally

npx cursor-lint

The command scans .cursorrules and .cursor/rules/*.mdc in the project directory. No configuration or additional dependencies are required.

Example Output

.cursor/rules/bad.mdc
  ✗ Missing YAML frontmatter
    → Add --- block with description and alwaysApply: true

.cursor/rules/typescript.mdc
  ✓ All checks passed

1 error, 1 passed

Verify a Single File

npx cursor-lint --verify .cursor/rules/typescript.mdc

Generate a Starter Rule

npx cursor-lint --init typescript

Using cursor-lint in CI

Add the following GitHub Actions workflow to run the linter on every push and pull request:

# .github/workflows/lint-cursor-rules.yml
name: Lint Cursor Rules
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cursorrulespacks/cursor-lint-action@v1

If any rule has issues, the workflow fails, preventing broken .mdc files from being merged.

Why It Matters

• Solo developers: Running npx cursor-lint before committing catches errors early.
• Teams: Storing .cursor/rules/ in the repository ensures consistent AI behavior. CI linting eliminates the “works on my machine” problem where a teammate’s rule edit silently breaks front‑matter.
• Common pitfalls: Copy‑pasting a .cursorrules example from the internet often omits alwaysApply: true, causing the rule to be ignored in agent mode. cursor-lint flags this automatically.

Resources

• npm package: cursor-lint
• GitHub Action: cursor-lint-action
• VS Code / Cursor extension: Available on OpenVSX
• Sample rules: 77 tested .mdc rules are provided as a starting point

If your repository’s rules need a thorough audit, I offer a $50 async setup audit (code FIRSTAUDIT for 20 % off).