Agent Skills vs Cursor Rules: When to Use Each

Cursor gives you two ways to customize the AI agent: rules and skills. Both are markdown files. Both influence how the agent behaves. The distinction isn’t immediately obvious, and getting it wrong means wasting context window space or missing the behavior you wanted.

Here’s how they differ and when to reach for each one.

What Rules Are

Rules are .mdc files stored in .cursor/rules/. They have YAML frontmatter that controls when they load:

---
description: TypeScript coding standards
globs: "**/*.ts"
alwaysApply: false
---

# TypeScript Standards

- Use `const` by default, `let` only when reassignment is needed
- Explicit return types on exported functions
- No `any` types without a justifying comment

Rules have two loading modes:

Always apply. Set alwaysApply: true and the rule injects into every conversation, regardless of what you’re working on. Use this for universal standards you never want the agent to ignore.

File-glob matching. Set a globs pattern like **/*.tsx and the rule loads only when you’re working with matching files. Use this for file-type-specific conventions.

If a rule has neither alwaysApply nor globs, it won’t load consistently. Always configure one or the other.

What Skills Are

Skills are SKILL.md files stored in .cursor/skills/ (project-level) or ~/.cursor/skills/ (personal). They use simpler frontmatter:

---
name: deploy-checklist
description: Guide the deployment process for production releases. Use when the user mentions deploying, releasing, or pushing to production.
---

# Deploy Checklist

1. Ensure all tests pass: `npm test`
2. Build the production bundle: `npm run build`
3. Tag the release: `git tag v$(node -p "require('./package.json').version")`
4. Push the tag: `git push --tags`
5. Deploy: `npm run deploy:prod`
6. Verify health check within 5 minutes

Skills load based on relevance. The agent reads the description field of every available skill and decides whether the current task matches. If it does, the skill loads. If not, it stays out of the context window entirely.

The Key Differences

Aspect	Rules	Skills
Format	.mdc files	SKILL.md in a folder
Loading	Config-driven (alwaysApply, globs)	Agent decides based on description
Portability	Cursor only	Open standard (Cursor, Claude Code, Copilot, Codex, etc.)
Context cost	Always-on rules consume tokens every session	Only loaded when relevant
Priority	Higher: rules override skills when they conflict	Lower: defers to rules
Supporting files	Content only	Can include scripts, reference docs, assets

The most important distinction: rules are deterministic and skills are intelligent. A rule with alwaysApply: true loads every time, no exceptions. A skill loads only when the agent thinks it’s relevant. That makes rules more predictable and skills more efficient.

When to Use Rules

Rules work best for things that should always be active, regardless of what you’re working on.

Coding standards. “Use const by default.” “No default exports.” “Explicit return types.” These apply to every file of a given type and should never be skipped. Use a rule with globs.

Naming conventions. “Components are PascalCase.” “API routes are kebab-case.” “Database columns are snake_case.” The agent should follow these whether you’re writing a component or a migration. Use alwaysApply: true.

Don’t-do-this rules. “Never use eval.” “Don’t add new dependencies without asking.” “Never commit secrets.” These are constraints, not workflows. Rules enforce constraints better than skills because they’re always present.

Style preferences. “Use single quotes.” “Indent with 2 spaces.” “Write comments only for non-obvious logic.” File-glob rules catch these every time the agent touches a matching file.

When to Use Skills

Skills work best for multi-step workflows, portable conventions, and knowledge that’s only relevant some of the time.

Deployment workflows. A deployment process has specific steps, validation checkpoints, and conditional logic. It only matters when you’re deploying. Making it a skill keeps it out of the context window during normal coding.

PR and commit conventions. Writing commit messages and PR descriptions follows a template. A skill with a good description triggers automatically when you’re committing or creating a PR, and stays quiet otherwise.

Onboarding documentation. “Here’s how our API is structured, here’s where the models live, here’s how we handle auth.” A skill can include reference files that the agent pulls in only when needed, keeping everyday conversations lean.

Cross-tool workflows. If you switch between Cursor and Claude Code, or use Codex for some tasks, skills are the only option that works across all of them. Rules are Cursor-specific.

What Happens When They Conflict

Rules take priority. If a rule says “always use semicolons” and a skill says “no semicolons,” the rule wins. This is by design: rules are your hard constraints, skills are your workflows. The constraint layer should always override the workflow layer.

In practice, conflicts are rare if you separate concerns properly. Rules handle style and constraints. Skills handle processes and templates.

Migration Guide

If you already have rules and want to add skills, don’t migrate everything. Here’s a framework:

Keep as rules:

• Coding style and formatting
• Naming conventions
• Security constraints
• File-type-specific patterns
• Anything with alwaysApply: true that genuinely should always apply

Move to skills:

• Multi-step workflows (deployment, release, onboarding)
• Template-based outputs (PR descriptions, changelogs, documentation)
• Conditional processes (database migrations, API versioning)
• Anything you want to use across multiple AI tools

Delete or consolidate:

• Rules without alwaysApply or globs that aren’t loading reliably
• Duplicate instructions that appear in both rules and project READMEs
• Overly verbose rules that could be a skill with progressive disclosure

A Practical Setup

Here’s what a well-organized project might look like:

.cursor/
  rules/
    typescript.mdc      # alwaysApply: false, globs: **/*.ts
    react.mdc           # alwaysApply: false, globs: **/*.tsx
    no-secrets.mdc      # alwaysApply: true
  skills/
    deploy/
      SKILL.md          # Deployment workflow
    pr-template/
      SKILL.md          # PR description format
    db-migrations/
      SKILL.md          # Database migration process
      reference.md      # Schema conventions

Rules handle the always-on constraints. Skills handle the sometimes-relevant workflows. No overlap, no conflict, minimal context window waste.

The goal isn’t to have the most rules or the most skills. It’s to give the agent exactly the context it needs for the task at hand, and nothing more.