Run cursor-doctor in CI with GitHub Actions

Lint your Cursor rules automatically to catch broken frontmatter and invalid globs.

Why lint rules in CI

Rules with broken frontmatter or invalid globs fail silently. Cursor won't tell you the rule is broken, it just won't load. Running cursor-doctor check in CI catches these issues before they reach your team.

• Catch frontmatter errors: Missing fields, invalid YAML, wrong data types
• Validate globs: Make sure glob patterns are syntactically correct
• Flag vague rules: Detect overly generic instructions that waste tokens
• Fail PRs early: Block merges that would break your rules setup

The check command

The check command scans your .cursor/rules/ directory and returns an exit code based on what it finds:

npx cursor-doctor check

Exit codes:

• 0: Setup is healthy (no issues found)
• 1: Issues found (warnings or errors)

Any issue causes the build to fail, which is what you want in CI. If something is wrong with your rules, you'll know before merging.

GitHub Actions workflow

Add this workflow to .github/workflows/lint-cursor-rules.yml to check rules on every push:

name: Lint Cursor Rules

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint-rules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Check Cursor rules
        run: npx cursor-doctor check

This workflow runs on every push and PR to main. If npx cursor-doctor check exits with code 2, the workflow fails and blocks the merge.

Using lint for more detail

The check command gives a pass/fail health grade. For a detailed breakdown of every issue in every file, use lint instead:

- name: Lint Cursor rules
  run: npx cursor-doctor lint

The lint command exits with code 1 if any errors are found, 0 otherwise. It shows each issue with file path, severity, and a hint for fixing it.

What the check command catches

The linter validates frontmatter structure, glob syntax, and rule quality:

Errors

• Missing or malformed YAML frontmatter
• Rules that will never load (alwaysApply: false with no globs)
• Empty rule bodies (frontmatter but no instructions)
• Conflicting instructions within a rule

Warnings

• Missing or empty description
• Vague instructions ("write clean code", "follow best practices")
• No code examples in long rules
• Overly broad or invalid glob patterns
• Unknown frontmatter keys

Running locally before committing

Run the same check locally to catch issues before pushing:

npx cursor-doctor check

Fix any errors or warnings, then commit. Your CI workflow will pass on the first try.

Other CI platforms

The check command works in any CI environment that supports Node.js. For GitLab CI, CircleCI, or Jenkins, install Node and run npx cursor-doctor check the same way. The exit code behavior is identical.

Related guides

• How to write Cursor rules that actually work
• How to fix Cursor rule conflicts
• Sharing Cursor rules across a team

npx cursor-doctor check