What are Cursor skills?

A skill is a portable, version-controlled package that teaches an agent how to perform a domain-specific task. It is a folder containing a SKILL.md file, optionally alongside scripts, references and assets. Agent Skills is an open standard, so a skill written for Cursor works with any agent that supports it.

Where do I put a Cursor skill?

Project skills go in .agents/skills/ or .cursor/skills/ inside the repository. Personal skills go in ~/.agents/skills/ or ~/.cursor/skills/ on your own machine. Cursor also loads from .claude/skills/ and .codex/skills/ for compatibility.

How does Cursor decide when to use a skill?

It reads the description field. Cursor presents available skills to the agent, and the agent decides relevance from context, which makes that one line the most important thing in the file. Write it as what the skill does and when to use it, not as a title.

How do I force a skill to run?

Type / in Agent chat and select it by name, which attaches the skill to that one message. To keep it active for a whole session, invoke it as a Custom Mode with Option+Enter on Mac or Alt+Enter on Windows. Setting disable-model-invocation: true stops the agent applying it automatically at all.

How do I scope a skill to certain files?

Use the paths frontmatter field with glob patterns, as a list or a comma-separated string. The skill is then only surfaced when the agent is reading or editing matching files, which keeps file-specific guidance out of context for unrelated work.

Do skills work with cloud agents?

Project skills committed to the repository do. Personal skills in ~/.cursor/skills/ stay on your machine unless you turn on Sync Skills for Cloud Agents, and synced skills stay private to you rather than being shared with your team. Cursor does not copy ~/.agents/skills/ or unsynced local skills to cloud agents, remote SSH sessions, or self-hosted workers.

Can skills run scripts?

Yes. A skill can include a scripts/ directory with executable code in any language, referenced from SKILL.md using relative paths. The agent reads the instructions and runs the scripts when the skill is invoked, which is what makes skills more than a prompt fragment.

What is the difference between a skill and a rule?

Scope and capability. A rule is instruction text applied to the agent. A skill is a package that can also carry scripts, reference documents and assets, loads its resources progressively so context is not wasted, and can back a Custom Mode. Cursor ships a /migrate-to-skills skill for converting eligible rules.

Agent Skills

A folder with a SKILL.md in it, discovered automatically and loaded only when relevant. The mechanism is simple; the useful part is knowing which frontmatter field does what.

Open standard
Version controlled
Loaded progressively

Checked against cursor.com on 25 September 2026

The shape of a skill

A skill is a directory whose name is the skill's identity, containing a SKILL.md file. Everything else is optional.

.agents/
└── skills/
    └── deploy-app/
        ├── SKILL.md
        ├── scripts/
        │   ├── deploy.sh
        │   └── validate.py
        ├── references/
        │   └── REFERENCE.md
        └── assets/
            └── config-template.json

The three optional directories have defined roles. scripts/ holds executable code the agent can run, in any language. references/ holds documentation loaded on demand. assets/ holds templates, images and data files.

That split matters for context economy. Skills load progressively, so a large reference document sitting in references/ costs nothing until the agent decides it needs it. The same content pasted into SKILL.md would be in context every single time the skill is considered.

The file itself

---
name: react-component-patterns
description: Conventions for writing React components in this codebase.
paths:
  - "**/*.tsx"
  - "packages/ui/**/*.ts"
---

# React component patterns

## When to use
- Use this skill when creating or editing a component.

## Instructions
- Step-by-step guidance for the agent
- Domain-specific conventions

Two fields are required and one of them carries almost all the weight. The agent uses description to decide whether a skill is relevant, so it should read as a statement of what the skill does and when to reach for it. A description of "React stuff" will be ignored in situations where it would have helped.

Scoping, and why it is worth doing

The paths field limits a skill to files matching one or more globs. When set, the skill is only surfaced while the agent is working with matching files. This is not a small optimisation. In a repository with a dozen skills, unscoped guidance for Python conventions is competing for attention during a CSS change.

Nested directories give you the same effect for free. A .cursor/skills/ folder anywhere inside the repository is discovered, and skills found there are automatically scoped to files inside that directory. In a monorepo, putting a skill under apps/web/.cursor/skills/ scopes it to apps/web/ without any frontmatter at all.

Category folders are different: they are purely organisational. Grouping skills under shipping/ or debugging/ does not change scope, because a skill's identity comes from the folder containing SKILL.md, not from its parent.

Three ways a skill activates

Automatically. The default. The agent sees the available skills and picks based on context.
For one message. Type / in Agent chat and select the skill by name.
For a whole session. Invoke it as a Custom Mode with Option Enter on Mac or Alt Enter on Windows. An active mode shows a badge in the chat input, styled by the icon and color fields.

Setting disable-model-invocation: true removes the first option, turning the skill into a conventional slash command. That is the right choice for anything destructive, and the wrong choice for conventions you want applied consistently without having to remember them.

What travels and what does not

This trips people up when they first run a cloud agent. Project skills live in the repository and travel with it. Personal skills in ~/.cursor/skills/ stay on your machine until you turn on Sync Skills for Cloud Agents, and even then they stay private to you rather than being shared with your team.

Skills in ~/.agents/skills/ and unsynced local skills are not copied to cloud agents, remote SSH sessions in the Agents Window, or self-hosted workers at all. On a self-hosted worker, the documented options are project skills from the repository, or baking skills into the worker image.

Frontmatter fields, directory list and built-in skills transcribed from the Agent Skills documentation on 25 September 2026.

Frontmatter fields

SKILL.md frontmatter fields
Field	Required	What it does
name	Yes	Lowercase letters, numbers and hyphens. Must match the parent folder name.
description	Yes	What the skill does and when to use it. This is what the agent reads to decide relevance, so it is the highest-leverage line in the file.
paths	No	Glob patterns scoping the skill to matching files. A comma-separated string or a list. The legacy globs field still works but new skills should use paths.
disable-model-invocation	No	When true, the skill is only included when you explicitly type /skill-name. The agent will never apply it on its own.
icon	No	Badge icon when the skill is used as a Custom Mode. Names like code, terminal, bug, git-branch, book-open, beaker, shield, rocket. Defaults to a lightning icon.
color	No	Badge colour: default, green, cyan, blue, purple, magenta, orange, yellow, red or brand.
metadata	No	Arbitrary key-value mapping for anything else you want to carry.

Skills Cursor ships

Managed by Cursor and available without installing anything. They appear alongside your own, and the agent may invoke some automatically when a request clearly matches.

Authoring

/create-skill: Creates Agent Skills, including structure and SKILL.md files.
/create-rule: Creates Cursor rules with the appropriate scope and instructions.
/create-hook: Creates hooks and updates hooks.json for agent lifecycle events.
/create-subagent: Creates custom subagents with focused roles and delegation instructions.
/migrate-to-skills: Converts eligible dynamic rules and slash commands into Agent Skills.

Review and shipping

/review: Selects and runs the appropriate code-review agent.
/review-bugbot: Reviews code for likely bugs and regressions with Bugbot.
/review-security: Reviews code for security vulnerabilities with Security Review.
/split-to-prs: Splits large changes into smaller pull requests.
/autopilot: Monitors a pull request and addresses feedback, conflicts, failing checks and follow-up work.

Workflow and config

/automate: Creates Automations triggered by schedules, Slack messages, GitHub events and other sources.
/loop: Runs a prompt or skill repeatedly at a specified interval.
/shell: Runs the provided text as a literal shell command.
/statusline: Configures the Cursor CLI status line.
/update-cli-config: Updates CLI settings in ~/.cursor/cli-config.json.
/update-cursor-settings: Finds and updates the appropriate Cursor or VS Code setting.

Investigation and output

/cursor-blame: Investigates AI-authored changes and the prompts that produced them.
/canvas: Creates interactive React artifacts that render alongside the conversation.
/sdk: Helps you build applications and integrations with the Cursor SDK.

Frequently asked questions

What are Cursor skills?: A skill is a portable, version-controlled package that teaches an agent how to perform a domain-specific task. It is a folder containing a SKILL.md file, optionally alongside scripts, references and assets. Agent Skills is an open standard, so a skill written for Cursor works with any agent that supports it.
Where do I put a Cursor skill?: Project skills go in .agents/skills/ or .cursor/skills/ inside the repository. Personal skills go in ~/.agents/skills/ or ~/.cursor/skills/ on your own machine. Cursor also loads from .claude/skills/ and .codex/skills/ for compatibility.
How does Cursor decide when to use a skill?: It reads the description field. Cursor presents available skills to the agent, and the agent decides relevance from context, which makes that one line the most important thing in the file. Write it as what the skill does and when to use it, not as a title.
How do I force a skill to run?: Type / in Agent chat and select it by name, which attaches the skill to that one message. To keep it active for a whole session, invoke it as a Custom Mode with Option+Enter on Mac or Alt+Enter on Windows. Setting disable-model-invocation: true stops the agent applying it automatically at all.
How do I scope a skill to certain files?: Use the paths frontmatter field with glob patterns, as a list or a comma-separated string. The skill is then only surfaced when the agent is reading or editing matching files, which keeps file-specific guidance out of context for unrelated work.
Do skills work with cloud agents?: Project skills committed to the repository do. Personal skills in ~/.cursor/skills/ stay on your machine unless you turn on Sync Skills for Cloud Agents, and synced skills stay private to you rather than being shared with your team. Cursor does not copy ~/.agents/skills/ or unsynced local skills to cloud agents, remote SSH sessions, or self-hosted workers.
Can skills run scripts?: Yes. A skill can include a scripts/ directory with executable code in any language, referenced from SKILL.md using relative paths. The agent reads the instructions and runs the scripts when the skill is invoked, which is what makes skills more than a prompt fragment.
What is the difference between a skill and a rule?: Scope and capability. A rule is instruction text applied to the agent. A skill is a package that can also carry scripts, reference documents and assets, loads its resources progressively so context is not wasted, and can back a Custom Mode. Cursor ships a /migrate-to-skills skill for converting eligible rules.