Cursor has two systems for customizing AI behavior: .cursorrules files and SKILL.md skills. They solve different problems and work best together. Here's when to use each.
Quick Answer: Use .cursorrules for always-on project context (coding conventions, tech stack, style preferences). Use SKILL.md skills for on-demand workflows (code review, test generation, deployment). They complement each other — .cursorrules sets the baseline, skills add specialized capabilities.
| Feature | .cursorrules | SKILL.md Skills |
|---|---|---|
| Format | Plain text file | YAML frontmatter + markdown |
| Location | Project root | .cursor/skills/ directory |
| Activation | Always loaded | On-demand by description match |
| Scope | Entire project | Specific tasks |
| Multiple files | One per project | Unlimited per project |
| Cross-agent | Cursor only | 20+ agents (Claude Code, OpenClaw, Codex CLI, etc.) |
| Marketplace | None | Agensi |
What is a .cursorrules file?
A .cursorrules file is a plain text file placed in your project root. Cursor loads its contents into every conversation automatically. It's where you describe your project's conventions:
This project uses TypeScript with strict mode.
Use functional components with React hooks.
Prefer Tailwind utility classes over custom CSS.
Always use pnpm, never npm or yarn.
Error handling follows the Result pattern, not try/catch.
The content is unstructured — just write what you want Cursor to know. There's no frontmatter, no metadata, no folder structure. It's simple by design.
What is a SKILL.md skill?
A SKILL.md skill is a structured instruction file that teaches Cursor a specific workflow. It has YAML frontmatter that tells Cursor when to activate it, and a markdown body with detailed instructions.
---
name: code-reviewer
description: Use when the user asks to review code, find bugs, or check for security issues.
---
Code Review
Review the specified code for:
- Logic errors and bugs
- Security vulnerabilities
- Performance issues
- Style violations
Organize findings by severity... ```
Skills activate on demand — Cursor reads the description and loads the skill only when your request matches. This keeps irrelevant instructions out of context.
When should I use .cursorrules?
Use .cursorrules for information that applies to every interaction in your project:
- Programming language and framework choices
- Code style preferences (naming conventions, indentation, import ordering)
- Architecture patterns your team follows
- Which libraries to prefer or avoid
- How error handling should work
- Testing conventions
This is "always-on" context. You want Cursor to know these things regardless of what you're asking it to do.
When should I use SKILL.md skills?
Use skills for specific, repeatable workflows:
- Code review with structured severity ratings
- Test generation with framework-specific patterns
- Git commit message writing following conventional commits
- Documentation generation
- Deployment checklists
- Database migration validation
These are "on-demand" capabilities. You don't want code review instructions loaded into context when you're asking about CSS styling.
Can I use both simultaneously?
Yes, and you should. They serve different purposes:
.cursorrules tells Cursor "here's how we do things in this project." It provides the foundation — language, framework, conventions.
SKILL.md skills tell Cursor "here's how to do this specific task." They provide the specialized workflow on top of that foundation.
When both are active, Cursor combines them. A code review skill runs with your project's conventions in context, so it checks against your actual patterns, not generic ones.
How do I migrate .cursorrules to SKILL.md?
If you want to make your Cursor customizations portable across agents, convert your .cursorrules into SKILL.md format:
- Identify which parts of your .cursorrules describe specific workflows (these become skills)
- Identify which parts describe general project context (these stay in .cursorrules)
- For each workflow, create a SKILL.md with a clear description trigger
For example, if your .cursorrules contains both "always use TypeScript strict mode" and a detailed code review process, split them. The TypeScript preference stays in .cursorrules. The code review process becomes a skill.
For a related walkthrough, read How to Use SKILL.md in Cursor.
What about portability?
This is the biggest practical difference. .cursorrules only works in Cursor. SKILL.md works across 20+ agents including Claude Code, OpenClaw, Codex CLI, and Gemini CLI.
If you might switch tools or use multiple agents, SKILL.md is the safer investment. Write your workflows once, use them everywhere. Keep .cursorrules for Cursor-specific project context that doesn't need to be portable.
For a broader comparison of agent configuration formats, read SKILL.md vs CLAUDE.md vs .cursorrules.
Browse cross-compatible skills for Cursor, Claude Code, OpenClaw, and more on Agensi.