Cursor Skills: The Complete Guide (List, Examples, and Skills vs Rules)

Cursor has native Agent Skills since version 2.4 (January 2026): reusable capabilities you define in a SKILL.md file that the agent discovers and applies when they are relevant, or that you invoke by hand. If you searched for "Cursor skills," this is the feature you want — a folder with a SKILL.md that teaches Cursor a specific workflow. This guide covers what skills are, where they live, a shortlist of examples, and how they differ from the older .mdc rules.

What a Cursor skill is

A skill is a directory containing a SKILL.md file — Markdown with a little frontmatter (a name and a description) followed by the instructions. Alongside SKILL.md, a skill can bundle a scripts/ folder, references/, and assets/ the workflow needs:

.cursor/skills/
└── deploy-web/
    ├── SKILL.md
    ├── scripts/
    │   └── deploy.sh
    └── references/
        └── REFERENCE.md

Cursor reads the name and description first and loads the full instructions only when the skill is actually used, so a sharp description is what makes a skill trigger at the right moment.

Where skills live

Cursor loads skills from both project and global locations:

• Project — .cursor/skills/ (or .agents/skills/) at the repo root, and in any subdirectory, where they are automatically scoped to that folder.
• Global — ~/.cursor/skills/ (or ~/.agents/skills/), available in every project.

For compatibility, Cursor also loads skills from the Claude and Codex directories, so a SKILL.md written for another agent works here with no changes.

How you use a skill

Two ways, straight from how Cursor discovers them:

• Automatic — the agent decides a skill is relevant to your task and applies it on its own.
• Manual — type / in the Agent chat and search the skill by name to invoke it directly.

Skills vs rules: the distinction that matters

This is the question behind most "Cursor skills vs rules" searches, and the answer changed in v2.4. Cursor now has two distinct primitives:

• Rules (.mdc files in .cursor/rules/) are always-on, declarative context. They are best for standing conventions that should shape every relevant response: strict TypeScript, named exports, no secrets in code. You attach them with alwaysApply, a globs pattern, or a description.
• Skills (SKILL.md folders) are dynamic and procedural. They are best for "how-to" workflows the agent loads only when the task calls for it — deploy the app, write a migration, run the release checklist — and they can carry scripts and reference files.

Cursor's own framing: compared to always-on declarative rules, skills are better for dynamic context discovery and procedural instructions. In practice, use rules for what should always be true, and skills for a named job with steps. The two complement each other; you do not pick one over the other.

A shortlist of useful Cursor skills

Good candidates to package as skills:

• Deploy — the exact steps and scripts to ship your app, so the agent stops improvising them.
• Migration runner — how to create and apply a database migration in your stack.
• Release checklist — version bump, changelog, tag, publish.
• Test author — your testing conventions, with a scripts/ helper to run the suite.
• Code review — a "review this diff for bugs and security issues" workflow with a clear trigger description.
• Component scaffold — file structure, prop typing, and styling for a new component.

Because a skill is just a folder, keep each of these in .cursor/skills/ and commit them so your whole team gets the same behaviour.

Writing a skill Cursor actually uses

• Make the description a trigger, not a title. "Deploy the web app to production" beats "Deployment helper." The agent matches on it.
• Keep the body prescriptive. Concrete steps and the expected result, not vague advice.
• Push detail into files. Long procedures or scripts go in scripts/ and references/, so SKILL.md stays scannable.
• One job per skill. A skill that tries to do everything is hard to trigger and hard to trust.

Creating your first skill

Pick one repetitive task and package it. Create the folder and manifest:

mkdir -p .cursor/skills/deploy-web

Put a SKILL.md inside with a name, a description that says exactly when it applies, and the steps:

---
name: deploy-web
description: Build and deploy the web app to production
---

To deploy:
- Run the test suite; stop if anything fails.
- Build with the production config.
- Deploy, then confirm the health check returns 200.

Then ask Cursor to deploy — it should discover the skill from your request — or invoke it with / and the skill name. Commit the folder to share it with your team.

Where to go next

For ready-made ideas rather than writing every skill from scratch, browse our best Cursor skills shortlist, or the full skills catalog to filter by task. For workflows you can package as skills — testing, security, refactoring — the development category is a good starting point.

Skills and rules together give Cursor a clear division of labour: always-on guardrails in .cursor/rules/, named procedural workflows in .cursor/skills/. Set both up and the agent stops guessing and starts following your playbook.