The Complete Guide to Cursor Rules in 2026

What are Cursor rules?

Cursor rules are instructions that tell Cursor's AI exactly how to write code for your project. Instead of repeating the same context every chat message — "use TypeScript," "follow our naming conventions," "always add error handling" — you write it once in a rules file and Cursor applies it automatically.

Think of rules as a persistent system prompt that lives alongside your code. Every time Cursor generates, edits, or reviews code, it reads your rules first.

.cursorrules vs .cursor/rules/ folder

Cursor has evolved its rules system significantly. Here's the current state:

The .cursorrules file still works, but the .cursor/rules/ folder is the recommended approach in 2026. It lets you split rules into focused files — one for API conventions, one for testing patterns, one for component structure.

The .mdc format

Files in the rules folder use the .mdc (Markdown Cursor) format. Each file can include frontmatter metadata:

---
description: API route conventions for Next.js
globs: ["src/app/api/**/*.ts"]
alwaysApply: false
---

Always use the App Router route handler pattern.
Export async functions named GET, POST, PUT, DELETE.
Return NextResponse.json() for all responses.
Include proper error handling with try/catch.

The globs field tells Cursor to only apply this rule when editing matching files. The alwaysApply field controls whether the rule is always included in context or only when relevant files are open.

How to write effective Cursor rules

Good Cursor rules are specific, actionable, and include examples. Here's what works:

Be specific about your stack

## Tech stack
- Framework: Next.js 15 with App Router
- Language: TypeScript 5.7 (strict mode)
- Styling: Tailwind CSS v4
- Database: Drizzle ORM with PostgreSQL
- Testing: Vitest + React Testing Library

Show the pattern you want

## API route pattern

Every API route should follow this structure:

export async function POST(request: Request) {
  try {
    const body = await request.json();
    // validate input
    // business logic
    return NextResponse.json({ data: result });
  } catch (error) {
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 }
    );
  }
}

Set boundaries

## Do NOT
- Do not use the Pages Router — we are fully on App Router
- Do not use CSS modules — use Tailwind utility classes only
- Do not install new dependencies without asking first
- Do not use default exports for components — use named exports

Organizing rules for large projects

For larger codebases, split your rules by domain:

.cursor/rules/
  general.mdc          # Tech stack, coding style, naming
  api-routes.mdc       # API conventions, error handling
  components.mdc       # React component patterns
  database.mdc         # Drizzle schema, migration patterns
  testing.mdc          # Test structure, mocking patterns

Each file stays focused and maintainable. Developers can update the testing rules without touching API conventions.

Sharing Cursor rules across your team

The challenge with Cursor rules is collaboration. When rules live in .cursor/rules/, they're committed to git — which is great for one project. But what about sharing the same conventions across multiple repositories?

localskills.sh solves this. You publish your rules once to the registry, and anyone on your team installs them with a single command:

# Install the CLI
npm install -g @localskills/cli

# Install a shared skill into Cursor
localskills install your-team/api-conventions --target cursor

The skill is symlinked into .cursor/rules/, so updates propagate automatically when you run localskills pull.

Skills are versioned — every update creates a new version you can roll back from the dashboard. You can control visibility (public, private, or unlisted) and track downloads with built-in analytics.

Making Cursor rules work in Claude Code and Windsurf

The biggest limitation of .cursor/rules/ files is that they only work in Cursor. If your team uses Claude Code or Windsurf alongside Cursor, you're maintaining duplicate files.

With localskills.sh, one published skill installs into any combination of 8 tools:

# Install into Cursor, Claude Code, and Windsurf at once
localskills install your-team/api-conventions --target cursor claude windsurf

The CLI handles the format differences automatically — .mdc for Cursor, markdown for Claude Code's .claude/skills/, and the right format for Windsurf's .windsurf/rules/.

Read more about how agent skills work across tools or get started in 5 minutes.

---

Ready to share your Cursor rules across your team and tools? Install the CLI and publish your first skill today.

npm install -g @localskills/cli
localskills login
localskills publish