How to Use Skills in Cursor

By the RunLocalModel editorial team · October 10, 2026

Reference: https://cursor.com/docs/skills

A skill in Cursor is a folder you can commit. The folder teaches Agent one job, such as a pull-request checklist, a deploy script, or the house style for a package. The required file is SKILL.md. Scripts, templates, and longer notes can sit beside it. The layout is the Agent Skills open standard, so the same folder can be read by other agents that support it.

The steps below follow Cursor's documentation, Agent Skills. For what a skill folder is before you open Cursor, see What Are Agent Skills?

Run a skill

Cursor scans the skill directories at startup and gives Agent the list. Agent reads each skill's name and description, then opens the full instructions when the conversation matches. A clear description is what makes that choice work. Write it as a sentence about the job and the moment to use the skill.

To call a skill yourself, type / in Agent chat and search for the name. Cursor attaches that skill to the current message. Call it again on a later message if you still want it.

To keep a skill in context for the whole session, use it as a Custom Mode with Option+Enter on a Mac or Alt+Enter on Windows. The chat input shows a badge while the mode is on. Any skill with a valid frontmatter block can be a mode. The optional icon and color fields style that badge. The icon defaults to a lightning bolt. Color is one of default, green, cyan, blue, purple, magenta, orange, yellow, red, or brand. Icon names come from Cursor's set, including code, terminal, bug, git-branch, book-open, beaker, shield, and rocket. An unknown icon or color falls back to the default badge.

Skills Cursor already includes

Cursor ships a small set of built-in skills. They sit next to the skills you add, and Cursor maintains them. Type / and choose one. Agent may also apply a built-in skill when your request matches what that skill is for. /create-skill is the shortest way to draft a new folder.

Where to put your own skill

Cursor loads skills from these folders. A skill for one repository belongs in that repository, so a clone brings it along. A skill for every project on one machine belongs in the home directory.

Cursor also reads Claude and Codex skill folders, for compatibility: .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/.

Personal skills in ~/.cursor/skills/ stay on your computer until you sync them for Cloud Agents or publish them for your team. Skills under ~/.agents/skills/ stay on the machine. Cursor leaves that folder, and any personal skills you have not synced, off Cloud Agents, off remote SSH sessions in the Agents Window, and off self-hosted workers. On a self-hosted worker, use a skill committed in the repo, or include the skill in the worker image.

Each skill is a folder whose name matches the name field, with SKILL.md inside it:

.cursor/
└── skills/
    └── pr-notes/
        ├── SKILL.md
        ├── scripts/
        │   └── collect-commits.sh
        ├── references/
        │   └── release-tone.md
        └── assets/
            └── notes-template.md

Three extra folders are optional. scripts/ holds code the agent can run. references/ holds longer notes, loaded when the task needs them. assets/ holds templates, images, or other static files. Keep SKILL.md short and move the long material into those folders, so Agent loads the extra files only when it needs them.

You can group skills under category folders. Cursor walks the skills root and picks up every SKILL.md. The category folder is only for organization. The skill's identity is the folder that contains SKILL.md. In the tree below, the skills are land-a-pr and read-a-trace.

.cursor/
└── skills/
    ├── shipping/
    │   └── land-a-pr/
    │       └── SKILL.md
    └── debugging/
        └── read-a-trace/
            └── SKILL.md

A monorepo can keep a .cursor/skills/ or .agents/skills/ next to a package, anywhere in the tree. Cursor finds it. A skill there is offered when the agent is working on files inside that directory. A skill in the repository's top-level skills folder is available across the repo. Directory placement already limits the nested skill, so paths can stay unset.

Write SKILL.md

The file starts with YAML frontmatter, then the instructions in Markdown. name and description are required. name uses lowercase letters, numbers, and hyphens, and it must match the parent folder. Agent uses description to decide whether the skill is relevant, so say what it does and when to use it.

---
name: pr-notes
description: Drafts release notes from a pull request. Use when the user asks for a changelog entry, release notes, or a summary of what shipped.
---

# PR notes

## When to use

- The user asks for release notes or a changelog entry.
- The user asks what a pull request shipped.

## Instructions

- Read the diff and the linked issue before writing.
- Follow the tone in references/release-tone.md.
- Run scripts/collect-commits.sh when you need the commit list.
- Lead with the user-visible change. Keep ticket ids out of the first sentence.

Point at scripts and reference files with paths relative to the skill folder. The agent reads those instructions and runs the script. Bash, Python, JavaScript, and other formats the agent can execute are fine. Make each script self-contained, and print an error that says what failed.

Frontmatter fields

Older skills may still use globs. Cursor accepts that field as a fallback. New skills should use paths.

Limit a skill to certain files

Use paths when the skill should stay out of unrelated work. Agent sees it while reading or editing a file that matches a glob. Leave paths unset when the skill should be available no matter which file is open.

---
name: api-handler-style
description: Conventions for HTTP handlers in this service. Use when editing route or middleware files, or when the user asks for a new endpoint.
paths:
  - "src/routes/**/*.ts"
  - "src/middleware/**/*.ts"
---

The same patterns can be one comma-separated string: paths: "src/routes/**/*.ts, src/middleware/**/*.ts". Patterns use standard glob syntax.

Make a skill wait until you call it

By default, Agent may apply a skill when the description fits the task. Set disable-model-invocation to true when you want slash-command behavior: the skill enters the chat only after you type / and choose it.

---
name: pr-notes
description: Drafts release notes from a pull request. Use when the user asks for a changelog entry or release notes.
disable-model-invocation: true
icon: book-open
color: green
---

The icon and color lines style the Custom Mode badge. They are optional on a skill you only invoke with /.

See what Cursor found

Open Customize in the sidebar and go to Skills. Skills from the project and from plugins are listed with rules in the Agent Decides section. Cursor discovers skill folders when it starts, so this list is the check that the folder name, the name field, and SKILL.md line up.

Public examples of the same file format are in this site's Agent Skills browser. Read the source, including any scripts, before you use a skill you did not write.

Use personal skills with Cloud Agents

Skills in ~/.cursor/skills/ run on your machine. Turn on Sync Skills for Cloud Agents to use those same skills with Cloud Agents. Synced skills stay private to you.

1. Open Settings → Agents.
2. Under Context and Tools, turn on Sync Skills for Cloud Agents.
3. Confirm. Cursor copies ~/.cursor/skills/ so your Cloud Agents can use them.

You can start the same sync from Customize → Skills. Only ~/.cursor/skills/ syncs. Project skills, ~/.agents/skills/, and other files on the machine stay where they are.

To stop, turn Sync Skills for Cloud Agents off under Settings → Agents. Cursor moves the synced skills back to your machine.

Team admin controls

On Teams and Enterprise plans, an admin decides whether members can sync:

1. Open Team Settings.
2. Go to Security & Identity.
3. Turn Sync Skills for Cloud Agents off to disable sync for everyone on the team.

When the team setting is on, each person still chooses whether to sync. When it is off, nobody on the team can sync.

Sharing a skill with teammates is a separate step. Publish it to your team marketplace. Teammates can install the published skill, and Cursor stores a copy in a repository hosted for the team. Sync copies your personal skills onto your own Cloud Agents. Publishing puts a skill where the team can install it.

Install skills from a repository

A GitHub folder of skills is installed by packaging those skills in a plugin and installing the plugin from a marketplace. The repository needs a .cursor-plugin/marketplace.json file. Then do one of the following, and install the plugin:

• In Customize, import the repository with From GitHub Repository.
• Add the repository as a team marketplace.

The skills arrive with the plugin and show up in Customize with your other skills.

Move rules and slash commands into skills

Cursor 2.4 includes /migrate-to-skills. It converts two kinds of existing setup:

• Dynamic rules. Rules set to apply intelligently: alwaysApply is false or unset, and the rule has no globs. Those become ordinary skills.
• Slash commands. User-level and workspace commands become skills with disable-model-invocation: true, so they still run only when you call them.

1. Type /migrate-to-skills in Agent chat.
2. The agent finds the eligible rules and commands and converts them.
3. Review the new skills in .cursor/skills/.

Rules with alwaysApply: true, and rules that set globs, remain rules. Their trigger is different from a skill. User rules remain user rules, because they are stored outside the project files.

Questions people ask first

Related on this site

• What Are Agent Skills?, a plain-English guide to the folder format
• Agent Skills browser, a catalog of public SKILL.md files
• All guides