Cursor Skills: How to Use SKILL.md in Cursor (2026)

Cursor skills are reusable instruction packages that Cursor's agent loads on demand. Each skill lives in its own folder under .cursor/skills/, defined by a SKILL.md file with a name and description in frontmatter. The agent scans those descriptions up front, then pulls in the full instructions — plus any bundled scripts, templates, or reference docs — only when a task actually matches. That's the key difference from Cursor rules, which inject the same static text into context whether it's relevant or not.

This guide walks through the whole workflow: how Cursor's skills support works, a step-by-step .cursor/skills setup, when to reach for skills instead of rules, installing skills from a registry, reusing the same skills in Claude Code, and debugging skills that refuse to load.

How Cursor skills work

Cursor shipped native support for agent skills in late 2025, adopting the same SKILL.md convention that Claude Code popularized. If you're new to the concept, agent skills are folders of instructions and supporting files that an AI agent discovers and loads dynamically instead of carrying everything in its system prompt.

The mechanics in Cursor:

• Discovery. Cursor looks for skills in .cursor/skills/<skill-name>/SKILL.md inside your project, and in ~/.cursor/skills/ for personal skills that apply across every project.
• Progressive disclosure. At session start, the agent only sees each skill's name and description from the frontmatter — a few dozen tokens per skill. When your request matches a description, the agent reads the full SKILL.md body.
• Bundled files. A skill folder can contain more than the SKILL.md: reference docs, code templates, and scripts the agent can read or run when the skill activates. The agent loads those secondary files only if the instructions point to them.

This is what makes skills scale where rules bloat. Twenty always-on rules cost you context on every request. Twenty skills cost you twenty one-line descriptions, and only the relevant one expands.

The SKILL.md format itself is deliberately simple — YAML frontmatter with name and description, then a markdown body. The SKILL.md format guide covers the full spec; here's the shape:

---
name: api-error-handling
description: Conventions for API error responses. Use when writing or
  reviewing route handlers, error middleware, or API client code.
---

## Error response shape

Every API error returns JSON with this structure:

{ "error": { "code": "string", "message": "string" } }

## Rules

- Never leak stack traces or internal messages to clients.
- Map validation failures to 422, auth failures to 401/403.
- Log the full error server-side with a request ID.

Setting up .cursor/skills step by step

Here's a clean .cursor/skills setup from zero. Total time: about five minutes.

1. Create the skills directory

From your project root:

mkdir -p .cursor/skills/testing-conventions

One folder per skill. The folder name should match the name field you'll put in frontmatter — lowercase, hyphen-separated.

2. Write the SKILL.md

Create .cursor/skills/testing-conventions/SKILL.md:

---
name: testing-conventions
description: How to write and structure tests in this repo. Use when
  creating, modifying, or debugging test files.
---

## Framework

- Vitest for unit tests, Playwright for e2e.
- Test files live next to source: foo.ts -> foo.test.ts.

## Patterns

- One describe block per exported function.
- Use test.each for input/output tables instead of copy-pasted cases.
- Mock at the module boundary only — never mock internal functions.

## Running tests

Run a single file with: pnpm vitest run src/lib/foo.test.ts

The description is the most important line in the file. It's the only part the agent sees before deciding whether to load the skill, so state both what the skill covers and when to use it.

3. Add supporting files (optional)

Skills can be multi-file packages. Drop templates or reference material next to the SKILL.md and mention them in the body:

.cursor/skills/testing-conventions/
├── SKILL.md
├── templates/
│   └── component.test.tsx
└── reference/
    └── mocking-guide.md

Then in SKILL.md: "For component tests, start from templates/component.test.tsx." The agent reads that file only when it needs it.

4. Test the skill

Open a new agent session (skills are discovered at session start) and give it a task that should trigger the skill — "write tests for src/lib/parser.ts". Watch whether the agent references your conventions. If you want a direct check, ask it explicitly: "use the testing-conventions skill to review this test file."

5. Commit it

.cursor/skills/ belongs in version control. Skills are shared team infrastructure, exactly like your ESLint config — review changes to them in PRs like any other code.

Cursor skills vs rules: when to use each

Cursor now has two persistent-instruction systems, and they solve different problems. Rules (.cursor/rules/*.mdc, plus the legacy .cursorrules file) are covered in depth in our Cursor rules guide; here's how they compare to skills:

The practical split:

• Use rules for things that must always hold. "TypeScript strict mode, no any", "never commit secrets", "use our Button component, not raw buttons". These are cheap, short, and genuinely universal — always-on is correct.
• Use skills for everything situational. Release checklists, database migration procedures, API design conventions, framework-specific patterns that only matter in part of the codebase. Anything long enough that you'd resent paying its token cost on every unrelated request.

A good smell test: if a rule file has grown past ~50 lines or only applies to certain tasks, it wants to be a skill. Cursor agent skills give you room for real depth — worked examples, edge cases, full procedures — without taxing every session.

Installing Cursor skills from a registry

Writing every skill from scratch is the slow path. A registry gives you two things: prebuilt skills for common stacks, and a single source of truth for your team's own skills instead of files copy-pasted between repos.

With localskills, installation is one command:

npm install -g @localskills/cli
localskills login
localskills install acme/api-conventions --target cursor

The CLI takes one published skill — a package with a root SKILL.md — and writes Cursor's native project format for you (for Cursor that's .cursor/rules as .mdc files, so the guidance is picked up with zero manual conversion). Skills on the registry are versioned with rollback, can be public, private, or unlisted, and organizations get folders, teams, and per-folder access restrictions for internal skill libraries. Because a published skill is just a SKILL.md package, you can also vendor its folder straight into .cursor/skills/ if you prefer the on-demand loading path.

Updating is the same command again — you get the new version, and if it breaks something, the previous version is one rollback away on the registry side.

Reusing the same skills across Cursor and Claude Code

Most teams don't use one tool. Someone's in Cursor, someone's in Claude Code, someone's trying Windsurf this month. Maintaining separate .cursor/skills/, .claude/skills/, and .windsurf/rules/ copies of the same knowledge is how instructions drift apart.

The fix is to treat SKILL.md as your canonical format and generate everything else. Since a skill is plain markdown with frontmatter, one source can serve every tool:

localskills install acme/api-conventions --target cursor claude windsurf

One install writes each tool's native format from the same published skill — .cursor/rules for Cursor, .claude/skills/ for Claude Code, .windsurf/rules/ for Windsurf. When the skill gets a new version, every tool picks it up from the same source. If your team's guidance currently lives in a pile of .cursorrules files, the migration guide from .cursorrules to shared skills walks through converting them once and never hand-syncing again.

For teams that want Git as the review surface, localskills also supports bidirectional GitHub sync: your org's skill library mirrors to a repo, and edits merged in the repo import back as new skill versions.

Troubleshooting Cursor skills that don't load

Skills failing silently is the most common complaint, and it's almost always one of these:

1. Wrong path or filename. The file must be exactly .cursor/skills/<skill-name>/SKILL.md — uppercase SKILL.md, one directory per skill, no nesting the markdown file deeper. .cursor/skills/my-skill.md won't be discovered.
2. Broken frontmatter. Missing --- fences, tabs in the YAML, or a missing name/description field will keep a skill out of the index. Validate the frontmatter first when a skill never appears.
3. Vague description. If the description is "Helpful coding tips", the agent has no signal for when to load it. Rewrite it to name concrete triggers: file types, tasks, technologies. "Use when writing SQL migrations or editing files in db/migrations/" triggers reliably.
4. Stale session. Skills are discovered when an agent session starts. If you just added or edited a skill, start a new chat before judging whether it works.
5. Name mismatch. Keep the folder name and the frontmatter name field identical. Mismatches are a classic source of skills that half-work.
6. Old Cursor version. Skills support is a recent addition — if the .cursor/skills directory is being ignored entirely, update Cursor before debugging anything else.
7. The skill loads but gets ignored. That's usually a conflict: an always-on rule contradicts the skill, and the rule wins by being in context first. Audit .cursor/rules/ for overlap and keep each piece of guidance in exactly one place.

A fast diagnostic for cases 1–5: explicitly ask the agent to "use the <name> skill". If it can't find the skill by name, the problem is discovery (path, frontmatter, session). If it can, the problem is the description not matching your prompts.

FAQ

Do Cursor skills replace Cursor rules?

No — they layer. Rules remain the right tool for short, always-true constraints; skills handle situational procedures and deep reference material that shouldn't occupy context on every request. Most mature setups end up with a handful of small rules and a larger library of skills.

Where does Cursor look for SKILL.md files?

Project skills live in .cursor/skills/<skill-name>/SKILL.md relative to the workspace root. Personal skills that follow you across projects live in ~/.cursor/skills/. Project skills belong in version control; personal ones don't.

Can I use my Claude Code skills in Cursor?

Yes. Both tools use the same SKILL.md convention, so a well-written skill ports directly — copy the folder from .claude/skills/ into .cursor/skills/ and it works. The cleaner long-term setup is publishing the skill once to a registry and installing it into both tools with --target cursor claude, so there's a single versioned source instead of divergent copies.

How big can a skill be?

Keep the SKILL.md body focused — a few hundred lines at most — and push bulk material into supporting files the agent loads on demand. On the registry side, localskills packages support multi-file skills up to 100 MB and 500 files per version, which is far more room than any single skill should need.

---

Ready to stop copy-pasting instructions between repos and tools? Create a free localskills account and publish your first shared skill in minutes.

npm install -g @localskills/cli
localskills login