I built a linter for cursor rules (npx cursor-lint)

Showcase Built for Cursor
1

I kept seeing threads here asking “how do I know if my rules are even working?” and the usual answer is to add a test marker like “always respond with :t_rex:” and see if it shows up.

That works but it’s kind of a pain, especially if you have multiple .mdc files and want to check them all.

So I made a quick CLI tool that scans your project and flags common mistakes:

npx cursor-lint

It checks for:

  • using .cursorrules instead of .mdc files (agent mode ignores .cursorrules)
  • missing alwaysApply: true in frontmatter
  • vague rules that don’t actually change output (“write clean code”, etc.)
  • broken YAML frontmatter
  • comma-separated globs instead of arrays

No install, no config, just run it in your project directory. Exit code 1 on errors so you can throw it in CI if you want.

GitHub: GitHub - cursorrulespacks/cursor-lint: Lint your Cursor rules — catch common mistakes before they break your workflow

It’s pretty basic right now (v0.1) but if there are other checks you’d want, let me know. Curious what mistakes other people keep running into

3

update: cursor-lint has been renamed to cursor-doctor and expanded into a full diagnostic tool. same engine, but now it also catches rule conflicts across files, finds redundant rules wasting your context window, and detects missing rules for your stack.

free scan still works the same way:

npx cursor-doctor scan

gives you a health grade (A-F) based on 8 checks. if you were using cursor-lint before, just swap to cursor-doctor.