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.

Overview Table

| 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, rules, and baseline context that the AI should always keep in mind when assisting you. Typical examples include your tech stack, coding style preferences, architecture notes, and other persistent guidelines.

Practical Examples of .cursorrules Content

Here are some example snippets you might find in a .cursorrules file: 1. "This project uses TypeScript with strict mode enabled." 2. "Use functional components with React hooks instead of class components." 3. "Prefer Tailwind CSS utility classes over custom CSS." 4. "Always manage dependencies with pnpm; npm or yarn are not allowed." 5. "Handle errors using the Result pattern instead of try/catch blocks." These simple declarative statements help the AI maintain consistent advice and code generation aligned with your project’s standards.

How .cursorrules Helps You

- Consistency: AI suggestions always honor your established coding conventions. - Context: The AI understands your tech stack and usage patterns, avoiding irrelevant answers. - Efficiency: You don’t need to restate project rules in every prompt.

Steps to Create a .cursorrules File

1. In your project root, create a new file named `.cursorrules`. 2. Write plain text paragraphs detailing your project’s conventions and preferences. 3. Save the file and reload your Cursor workspace. 4. Start chatting with the AI; it now incorporates these rules automatically.

Tip

Keep the .cursorrules file concise but comprehensive. Focus on critical conventions and avoid overly verbose descriptions which may dilute AI focus.

What is a SKILL.md file?

SKILL.md files are specialized AI skills stored inside your project’s `.cursor/skills/` directory. Each skill is a self-contained YAML + markdown document describing a procedural workflow or task that the AI can perform on demand. Unlike .cursorrules, skills are not always active; they are triggered only when your prompt matches the skill’s description or intent.

Structure of a SKILL.md File

A typical SKILL.md starts with YAML frontmatter defining metadata like the skill name, description, and tags, followed by detailed markdown instructions or templates for the AI to follow.

Practical Examples of SKILL.md Skills

Here are some common skill types: 1. Code Review Skill: Automatically analyze a code snippet and provide feedback based on project standards. 2. Test Generation Skill: Generate unit tests for a given function or component. 3. Deployment Skill: Outline deployment steps or generate configuration files for specific environments. 4. Bug Fix Skill: Suggest fixes for common error messages or code smells. These skills allow you to automate repetitive or complex workflows with a single prompt.

Benefits of Using SKILL.md Skills

- On-demand activation: Skills load only when relevant, keeping interactions focused. - Specialized workflows: Define detailed, repeatable procedures the AI can execute. - Multi-agent support: Skills can be used across multiple AI agents beyond just Cursor, such as Claude Code or Codex CLI. - Marketplace availability: Access community-created skills via Agensi for quick onboarding.

How to Create a SKILL.md File

1. Inside your project, create a `.cursor/skills/` directory if it doesn’t exist. 2. Add a new file named descriptively, such as `code-review.SKILL.md`. 3. Write YAML frontmatter specifying name, description, and tags. 4. Compose markdown content detailing the step-by-step workflow or templates. 5. Save and test by invoking the skill in your prompt (e.g., "Run code review on this file").

Tip

Use clear, concise descriptions and examples in your skill markdown. The better the instructions, the more reliable the AI’s execution.

When to Use .cursorrules vs SKILL.md Skills

Choosing between .cursorrules and SKILL.md skills depends on your use case. Here’s a handy guide:

Use .cursorrules When:

1. You want the AI to always remember your project’s foundational context. 2. You need consistent coding style enforcement across all AI interactions. 3. You want to minimize repetition of basic rules in every prompt. 4. Your requirements are broad and apply globally to the entire project.

Use SKILL.md Skills When:

1. You have specific procedural tasks the AI should perform only on request. 2. You want to automate workflows like code reviews, testing, or deployment. 3. You need to encapsulate complex instructions that don’t fit in a simple ruleset. 4. You want to share or reuse skills across multiple projects or teams.

How They Complement Each Other

The real power comes from combining .cursorrules and SKILL.md skills effectively. Here’s how they work together: - Baseline + Specialization: .cursorrules sets the baseline context — your tech stack, style, and conventions — so every AI response respects it. - On-demand workflows: SKILL.md skills kick in when you need the AI to perform a specialized task beyond general assistance. - Consistency in skills: Skills can reference or assume the rules defined in .cursorrules, ensuring aligned outputs.

Real-World Use Case

Imagine you’re working on a React TypeScript project with strict style guidelines and a CI/CD pipeline: - Your `.cursorrules` might specify the use of functional components, TypeScript strict mode, Tailwind CSS, and pnpm for dependency management. - You create a `code-review.SKILL.md` that runs a checklist against submitted code snippets, checking for adherence to these conventions. - Another skill, `generate-tests.SKILL.md`, produces unit tests based on the current project setup. When a developer wants a code review, they simply invoke the skill. The AI applies the baseline rules from .cursorrules and executes the review workflow from the SKILL.md, providing targeted, context-aware feedback.

Step-by-Step Guide to Combining Both

1. Define your .cursorrules: Write your project’s foundational rules and save them in the root. 2. Create your SKILL.md skills: Develop skills for common workflows or complex tasks. 3. Test each skill independently: Ensure they trigger correctly and produce expected outputs. 4. Invoke skills in context: Use prompts that activate skills when needed, while the AI always respects .cursorrules. 5. Iterate and refine: Update .cursorrules as project standards evolve; expand skills to cover new workflows.

Tips for Maximizing Productivity

- Keep .cursorrules focused on immutable rules: Don’t overload with transient instructions. - Modularize skills: Break complex workflows into smaller, reusable skill files. - Use descriptive tags in SKILL.md: Makes skill discovery easier. - Leverage marketplace skills: Don’t reinvent the wheel; customize existing skills from Agensi. - Regularly review and update: Ensure .cursorrules and skills reflect current project needs.

Conclusion

Both .cursorrules files and SKILL.md skills are essential tools in Cursor’s AI customization toolkit. Use .cursorrules to provide persistent project context that guides every AI interaction. Use SKILL.md skills to define powerful, on-demand workflows that automate complex tasks. Together, they create a seamless, efficient developer experience that adapts to your project’s evolving needs.

Further Resources

- Cursor Documentation: Learn more about .cursorrules and SKILL.md syntax and best practices. - Agensi Marketplace: Explore and import community-created skills. - PromptSpace Blog: Stay updated with tutorials and examples on maximizing AI productivity with Cursor.