How to Use SKILL.md in Cursor

SKILL.md files work in Cursor just like .cursorrules files. Drop them in your project root, and they'll get picked up automatically. The difference? SKILL.md files define reusable agent capabilities while .cursorrules set project-wide behavior.

Most developers discover this by accident. They see a promising skill on mdskills.ai, download it, then wonder where it goes. The answer depends on what you're trying to accomplish.

Where to put SKILL.md files

Project root works for most cases. Cursor loads any SKILL.md file it finds there, same as .cursorrules. You can also create a skills/ directory and organize multiple files:

your-project/
├── .cursorrules
├── SKILL.md
└── skills/
    ├── api-testing.skill.md
    ├── error-handling.skill.md
    └── typescript-types.skill.md

Cursor reads all .skill.md files recursively. Name them whatever makes sense, just keep the extension.

The global approach puts skills in ~/.cursor/ so they work across all projects. This makes sense for general capabilities you always want available, like code review patterns or debugging workflows.

Loading behavior differences

Cursor processes SKILL.md files differently than Claude Code (which started this format). Cursor concatenates all skills into the system prompt alongside .cursorrules content. Claude Code treats each skill as a separate context injection.

This matters for skill interactions. If you have conflicting instructions across multiple skills, Cursor will see all of them simultaneously. Design skills to be modular rather than comprehensive.

Token limits hit faster with multiple skills loaded. A single complex skill might use 2000 tokens. Five skills can push you over the context window before you write any code. Browse skills by size to understand the impact.

Skills with example code blocks consume the most tokens. The SKILL.md spec recommends keeping examples under 10 lines for this reason.

What works differently

File watching in Cursor means skills reload automatically when you edit them. Change a skill definition, and Cursor picks up the changes on the next prompt. No restart needed.

The .cursorrules file takes precedence over skills when instructions conflict. Think of .cursorrules as project-specific overrides and skills as general capabilities you can drop into any project.

Multi-turn conversations work better with skills than traditional prompting. Skills give Cursor consistent context about your preferred patterns. Instead of re-explaining your API testing approach each time, load a skill once and reference it throughout the session.

Combining skills effectively

Start with one skill and verify it works before adding more. Download a simple skill like error handling, test it on a few functions, then expand.

Skills compose well when they target different concerns. A TypeScript types skill pairs nicely with an API client skill because they operate on different parts of your codebase. Two skills that both handle state management will create confusion.

Check for instruction overlap before loading multiple skills. If both skills mention "use async/await", they'll reinforce each other. If one says "use callbacks" and another says "avoid callbacks", Cursor has to pick one approach.

Some developers create a master .cursorrules file that explicitly loads skills:

Follow instructions from loaded skills in this order:
1. TypeScript patterns from typescript-types.skill.md
2. API design from api-patterns.skill.md  
3. Error handling from error-handling.skill.md

When skills conflict, prioritize the higher-numbered skill.

This gives you explicit control over precedence.

Common gotchas

Skills written for Claude Code sometimes include conversational elements that don't translate well to Cursor's batch processing. A skill that says "Ask me for clarification if the requirements are unclear" won't work the same way in Cursor's context.

File paths in skills need to be relative or generic. A skill hardcoded to look for files in /src/components/ won't work in projects that use /app/ or /lib/.

Version conflicts happen when skills assume specific tool versions. A skill written for Jest 27 might suggest APIs that don't exist in Jest 29. Check skill documentation for compatibility notes.

Testing new skills

Create a test project with minimal code to verify skill behavior. Don't load a new skill into your main project until you understand what it does.

Ask Cursor to explain the loaded skills: "What capabilities do you currently have from the SKILL.md files?" This shows you how Cursor interprets the instructions.

Test edge cases by giving Cursor tasks that touch multiple skills. If you have both testing and error handling skills loaded, ask it to write a test for error conditions.

Remove skills that don't get used. Every loaded skill consumes context tokens, even when irrelevant to your current task.

Creating project-specific skills

Not every skill needs to be reusable. Create project-specific skills for unique patterns in your codebase. A skill that knows your database schema or API conventions can be more valuable than generic advice.

Document dependencies in your skill files. If a skill assumes you're using Next.js, say so explicitly. This prevents confusion when someone loads it in a different environment.

Version your custom skills alongside your project. When you refactor major patterns, update the corresponding skill files. This keeps the AI assistance aligned with your current approach.

The best practices guide covers writing maintainable skills that work well in team environments.

Skills transform Cursor from a generic coding assistant into something that understands your specific patterns and preferences. Load them thoughtfully, test them thoroughly, and treat them as living documentation of how you want code written.