Creating Cursor Rules Skill

---
name: creating-cursor-rules-skill
description: Expert guidance for creating effective Cursor IDE rules with best practices, patterns, and examples
---

# Creating Cursor Rules

You are an expert at creating effective `.cursor/rules` files that help AI assistants understand project conventions and produce better code.

## When to Apply This Skill

**Use when:**
- User is starting a new project and needs `.cursor/rules` setup
- User wants to improve existing project rules
- User asks to convert skills/guidelines to Cursor format
- Team needs consistent coding standards documented

**Don't use for:**
- One-time instructions (those can be asked directly)
- User-specific preferences (those go in global settings)
- Claude Code skills (this skill is specifically for Cursor rules)

## Core Principles

### 1. Be Specific and Actionable

Rules should provide concrete guidance, not vague advice.

**❌ BAD - Vague:**
```markdown
Write clean code with good practices.
Use proper TypeScript types.
```

**✅ GOOD - Specific:**
```markdown
Use functional components with TypeScript.
Define prop types with interfaces, not inline types.
Extract custom hooks when logic exceeds 10 lines.
```

### 2. Focus on Decisions, Not Basics

Don't document what linters handle. Document architectural decisions.

**❌ BAD - Linter territory:**
```markdown
Use semicolons in JavaScript.
Indent with 2 spaces.
Add trailing commas.
```

**✅ GOOD - Decision guidance:**
```markdown
Choose Zustand for global state, React Context for component trees.
Use Zod for runtime validation at API boundaries only.
Prefer server components except for: forms, client-only APIs, animations.
```

### 3. Organize by Concern

Group related rules into clear sections:

```markdown
## Tech Stack
- Next.js 14 with App Router
- TypeScript strict mode
- Tailwind CSS for styling

## Code Style
- Functional components only
- Named exports (no default exports)
- Co-locate tests with source files

## Patterns
- Use React Server Components by default
- Client components: mark with "use client" directive
- Error handling: try/catch + toast notification

## Project Conventions
- API routes in app/api/
- Components in components/ (flat structure)
- Types in types/ (shared), components/*/types.ts (local)
```

## Rule Anatomy

### MDC Format and Metadata

Cursor rules are written in **MDC (.mdc)** format, which supports YAML frontmatter metadata and markdown content. The metadata controls how and when rules are applied.

### Required YAML Frontmatter

Every Cursor rule MUST start with YAML frontmatter between `---` markers:

```yaml
---
description: Brief description of when and how to use this rule
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---
```

### Frontmatter Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `description` | string | **Yes** | Brief description of the rule's purpose. Used by AI to decide relevance. Never use placeholders like `---` or empty strings. |
| `globs` | array | No | File patterns that trigger auto-attachment (e.g., `["**/*.ts"]`). Leave empty or omit if not using Auto Attached type. |
| `alwaysApply` | boolean | No | If `true`, rule is always included in context. If `false` or omitted, behavior depends on Rule Type. |

### Rule Types

Control how rules are applied using the **type dropdown** in Cursor:

| Rule Type | Description | When to Use |
|-----------|-------------|-------------|
| **Always** | Always included in model context | Core project conventions, tech stack, universal patterns that apply everywhere |
| **Auto Attached** | Included when files matching `globs` pattern are referenced | File-type specific rules (e.g., React components, API routes, test files) |
| **Agent Requested** | Available to AI, which decides whether to include it based on `description` | Contextual patterns, specialized workflows, optional conventions |
| **Manual** | Only included when explicitly mentioned using `@ruleName` | Rarely-used patterns, experimental conventions, legacy documentation |

### Examples by Rule Type

**Always Rule** (Core conventions):
```yaml
---
description: TypeScript and code style conventions for the entire project
alwaysApply: true
---
```

**Auto Attached Rule** (File pattern-specific):
```yaml
---
description: React component patterns and conventions
globs: ["**/components/**/*.tsx", "**/app/**/*.tsx"]
alwaysApply: false
---
```

**Agent Requested Rule** (Contextual):
```yaml
---
description: RPC service boilerplate and patterns for creating new RPC endpoints
globs: []
alwaysApply: false
---
```

**Manual Rule** (Explicit invocation):
```yaml
---
description: Legacy API migration patterns (deprecated, use for reference only)
globs: []
alwaysApply: false
---
```

### Best Practices for Frontmatter

1. **Description is mandatory** - AI uses this to determine relevance. Be specific:
   - ❌ Bad: `Backend code`
   - ✅ Good: `Fastify API route patterns, error handling, and validation using Zod`

2. **Use globs strategically** - Auto-attach to relevant file types:
   - React components: `["**/*.tsx", "**/*.jsx"]`
   - API routes: `["**/api/**/*.ts", "**/routes/**/*.ts"]`
   - Tests: `["**/*.test.ts", "**/*.spec.ts"]`

3. **Avoid always applying everything** - Use `alwaysApply: true` sparingly:
   - ✅ Good for: Tech stack, core conventions, project structure
   - ❌ Bad for: Framework-specific patterns, specialized workflows

4. **Make Agent Requested rules discoverable** - Write descriptions that help AI understand when to use:
   - Include keywords: "boilerplate", "template", "pattern for X"
   - Mention specific use cases: "when creating new API routes"

## Required Sections

Every Cursor rule file should include these sections:

### 1. Tech Stack Declaration

```markdown
## Tech Stack
- Framework: Next.js 14
- Language: TypeScript 5.x (strict mode)
- Styling: Tailwind CSS 3.x
- State: Zustand
- Database: PostgreSQL + Prisma
- Testing: Vitest + Playwright
```

**Why:** Prevents AI from suggesting wrong tools/patterns.

### 2. Code Style Guidelines

```markdown
## Code Style
- **Components**: Functional with TypeScript
- **Props**: Interface definitions, destructure in params
- **Hooks**: Extract when logic > 10 lines
- **Exports**: Named exports only (no default)
- **File naming**: kebab-case.tsx
```

### 3. Common Patterns

Always include code examples, not just descriptions:

```markdown
## Patterns

### Error Handling
```typescript
try {
  const result = await operation();
  toast.success('Operation completed');
  return result;
} catch (error) {
  const message = error instanceof Error ? error.message : 'Unknown error';
  toast.error(message);
  throw error; // Re-throw for caller to handle
}
```

### API Route Structure
```typescript
// app/api/users/route.ts
export async function GET(request: Request) {
  try {
    // 1. Parse/validate input
    // 2. Check auth/permissions
    // 3. Perform operation
    // 4. Return Response
  } catch (error) {
    return new Response(JSON.stringify({ error: 'Message' }), {
      status: 500
    });
  }
}
```
```

## What NOT to Include

Avoid these common mistakes:

**❌ Too obvious:**
```markdown
- Write readable code
- Use meaningful variable names
- Add comments when necessary
- Follow best practices
```

**❌ Too restrictive:**
```markdown
- Never use any third-party libraries
- Always write everything from scratch
- Every function must be under 5 lines
```

**❌ Language-agnostic advice:**
```markdown
- Use design patterns
- Think before you code
- Test your code
- Keep it simple
```

## Structure Template

Use this template for new Cursor rules:

```markdown
# Project Name - Cursor Rules

## Tech Stack
[List all major technologies with versions]

## Code Style
[Specific style decisions]

## Project Structure
[Directory organization]

## Patterns
[Common patterns with code examples]

### Pattern Name
[Description + code example]

## Conventions
[Project-specific conventions]

## Common Tasks
[Frequent operations with step-by-step snippets]

### Task Name
1. Step one
2. Step two
[Code example]

## Anti-Patterns
[What to avoid and why]

## Testing
[Testing approach and patterns with examples]
```

## Example Sections

### Tech Stack Section

```markdown
## Tech Stack

**Framework:** Next.js 14 (App Router)
**Language:** TypeScript 5.x (strict mode enabled)
**Styling:** Tailwind CSS 3.x with custom design system
**State:** Zustand for global, React Context for component trees
**Forms:** React Hook Form + Zod validation
**Database:** PostgreSQL with Prisma ORM
**Testing:** Vitest (unit), Playwright (E2E)
**Deployment:** Vercel

**Key Dependencies:**
- `@tanstack/react-query` for server state
- `date-fns` for date manipulation (not moment.js)
- `clsx` + `tailwind-merge` for conditional classes
```

### Anti-Patterns Section

```markdown
## Anti-Patterns

### ❌ Don't: Default Exports
```typescript
// ❌ BAD
export default function Button() { }

// ✅ GOOD
export function Button() { }
```

**Why:** Named exports are more refactor-friendly and enable better tree-shaking.

### ❌ Don't: Inline Type Definitions
```typescript
// ❌ BAD
function UserCard({ user }: { user: { name: string; email: string } }) { }

// ✅ GOOD
interface User {
  name: string;
  email: string;
}

function UserCard({ user }: { user: User }) { }
```

**Why:** Reusability and discoverability.
```

## Common Tasks

Include shortcuts for frequent operations:

```markdown
## Common Tasks

### Adding a New API Route

1. Create `app/api/[route]/route.ts`
2. Define HTTP method exports (GET, POST, etc.)
3. Validate input with Zod schema
4. Use try/catch for error handling
5. Return `Response` object

```typescript
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(1)
});

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const data = schema.parse(body);

    // Process...

    return Response.json({ success: true });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return Response.json(
        { error: error.errors },
        { status: 400 }
      );
    }
    return Response.json(
      { error: 'Internal error' },
      { status: 500 }
    );
  }
}
```
```

## Best Practices

### Keep Rules Under 500 Lines

- Split large rules into multiple, composable files
- Each rule file should focus on one domain or concern
- Reference other rule files when needed (e.g., "See `backend-api.mdc` for API patterns")
- **Why:** Large files become unmanageable and harder for AI to process effectively

### Split Into Composable Rules

Break down by concern rather than creating one monolithic file:

```
.cursor/rules/
  ├── tech-stack.mdc          # Core technologies
  ├── typescript-patterns.mdc # Language-specific patterns
  ├── api-conventions.mdc     # API route standards
  ├── component-patterns.mdc  # React/UI patterns
  └── testing-standards.mdc   # Testing approaches
```

**Why:** Easier to maintain, update, and reuse across similar projects.

### Provide Concrete Examples or Referenced Files

Instead of vague guidance, always include:
- Complete, runnable code examples
- References to actual project files: `See components/auth/LoginForm.tsx for example`
- Links to internal docs or design system
- Specific file paths and line numbers when relevant

**❌ BAD - Vague:**
```markdown
Use proper error handling in API routes.
```

**✅ GOOD - Concrete:**
```markdown
API routes must use try/catch with typed errors. Example:
```typescript
// app/api/users/route.ts (lines 10-25)
export async function POST(request: Request) {
  try {
    const data = await request.json();
    return Response.json({ success: true });
  } catch (error) {
    return handleApiError(error); // See lib/errors.ts
  }
}
```
See `app/api/products/route.ts` for complete implementation.
```

### Write Rules Like Clear Internal Docs

Rules should read like technical documentation, not casual advice:
- Be precise and unambiguous
- Include the "why" behind decisions
- Document exceptions to rules
- Reference architecture decisions
- Link to related rules or documentation

**Think:** "Could a new engineer understand this without asking questions?"

### Reuse Rules When Repeating Prompts

If you find yourself giving the same instructions repeatedly in chat:
1. Document that pattern in `.cursor/rules/`
2. Include the specific guidance you keep repeating
3. Add examples of correct implementation
4. Update existing rule files rather than creating new ones

**Common scenarios to capture:**
- "Always use X pattern for Y"
- "Don't forget to Z when doing W"
- Corrections you make frequently
- Patterns specific to your team/codebase

### Keep It Scannable

- Use clear section headers
- Bold important terms
- Include code examples (not just prose)
- Use tables for comparisons
- Add table of contents for files over 200 lines

### Update Regularly

- Review monthly or after major changes
- Remove outdated patterns
- Add new patterns as they emerge
- Keep examples current with latest framework versions
- Archive deprecated rules rather than deleting (for reference)

### Test with AI

After creating rules, test them:

1. Ask AI: "Create a new API route following our conventions"
2. Ask AI: "Add error handling to this component"
3. Ask AI: "Refactor this to match our patterns"

Verify AI follows rules correctly. Update rules based on gaps found.

## Real-World Example

The PRPM registry `.cursor/rules` demonstrates:
- Clear tech stack declaration (Fastify, TypeScript, PostgreSQL)
- Specific TypeScript patterns
- Fastify-specific conventions
- Error handling standards
- API route patterns
- Database query patterns

## Checklist for New Cursor Rules

**Project Context:**
- [ ] Tech stack clearly defined with versions
- [ ] Key dependencies listed
- [ ] Deployment platform specified

**Code Style:**
- [ ] Component style specified (functional/class)
- [ ] Export style (named/default)
- [ ] File naming convention
- [ ] Specific to project (not generic advice)

**Patterns:**
- [ ] At least 3-5 code examples
- [ ] Cover most common tasks
- [ ] Include error handling pattern
- [ ] Show project-specific conventions

**Organization:**
- [ ] Logical section headers
- [ ] Scannable (not wall of text)
- [ ] Examples are complete and runnable
- [ ] Anti-patterns included with rationale

**Testing:**
- [ ] Tested with AI assistant
- [ ] AI follows conventions correctly
- [ ] Updated after catching mistakes

## Helpful Prompts for Users

When helping users create Cursor rules:

**Discovery:**
- "What's your tech stack?"
- "What patterns do you want AI to follow?"
- "What mistakes does AI currently make?"

**Refinement:**
- "Are there anti-patterns you want documented?"
- "What are your most common coding tasks?"
- "Do you have naming conventions?"

**Validation:**
- "Let me test these rules by asking you to generate code..."
- "Does this match your team's style?"

## Remember

- Cursor rules are **living documents** - update as project evolves
- Focus on **decisions**, not basics
- Include **runnable code examples**, not descriptions
- Test rules with AI to verify effectiveness
- Keep it **scannable** - use headers, bold, lists

**Goal:** Help AI produce code that matches project conventions without constant correction.