Cursor skills: how Agent Skills work in Cursor

Cursor skills are folders with a SKILL.md file that teach Cursor's agent a specific task, such as writing a migration or preparing a release. Cursor finds them at startup in .cursor/skills/ or .agents/skills/ (in your repo or your home directory), and the agent loads one when your request matches its description, or when you type / and pick it.

Skills follow the open Agent Skills format, so the same folder also works in other agents that support it, including Codex and Claude Code. For the format itself and how it works across agents, see our guide to agent skills and SKILL.md. The rest of this page is specific to Cursor.

What a Cursor skill is

A skill is a directory named after the skill, with a SKILL.md inside. The file starts with YAML frontmatter (at least a name and a description), followed by Markdown instructions. Next to it you can add a scripts/ folder for code the agent runs, references/ for longer docs, and assets/ for templates.

.cursor/skills/
  postgres-migration/
    SKILL.md
    scripts/
      check-migration.sh
    references/
      locking.md

.cursor/skills/
  postgres-migration/
    SKILL.md
    scripts/
      check-migration.sh
    references/
      locking.md

.cursor/skills/
  postgres-migration/
    SKILL.md
    scripts/
      check-migration.sh
    references/
      locking.md

Cursor's docs describe skills as portable packages that load supporting resources when needed. The Agent Skills spec explains the mechanism: at startup an agent reads only each skill's name and description, reads the full SKILL.md when a task matches, and opens bundled files only when the instructions call for them. That is why you can keep dozens of skills installed without filling the context window.

Where Cursor loads skills from

Cursor reads skills from project and user folders, plus the folders Claude Code and Codex use:

Cursor's docs add some details:

• The skill's name must match its folder name, in lowercase letters, numbers and hyphens.

• You can group skills in category subfolders.

• A skills folder inside a subdirectory, such as apps/web/.cursor/skills/, applies only to files in that directory, which helps in a monorepo.

• To see what Cursor found, open Customize in the sidebar and go to Skills. Project and plugin skills appear in the "Agent Decides" section next to your rules.

How the agent picks a skill

1. The agent decides. Cursor gives the agent every skill's description, and the agent loads a skill when your request matches it. A vague description means the skill rarely fires; a description that names the trigger ("Use when adding or changing a file in prisma/migrations") fires when it should.

2. You call it. Type / in Agent chat and pick the skill, or type @ and attach it as context. A skill you call this way applies to that one message. To keep it on for a whole session, use it as a Custom Mode (Option+Enter on Mac, Alt+Enter on Windows).

3. You scope it to files. The optional paths field takes glob patterns, so the skill only surfaces when matching files are involved. Cursor still accepts the older globs field as a fallback.

If a skill should never run on its own (deploys, anything that pushes or deletes), set disable-model-invocation: true. The skill then behaves like a classic slash command and runs only when you type /skill-name.

Cursor rules vs skills: when to use AGENTS.md

Rules, skills and AGENTS.md all give the agent instructions, so it's easy to put something in the wrong one. Cursor's own help page draws the line this way: rules are short guidelines applied automatically to matching conversations, and skills are longer procedures used on demand. AGENTS.md is plain Markdown with no metadata at all.

This is a packaging distinction. Rules and AGENTS.md can also instruct the agent to run commands; a skill keeps supporting scripts and references together. Tool permissions and approval settings still come from the agent and its environment.

Where to put what:

• If the agent needs it on every request ("use Env instead of process.env", "never commit to main"), make it an always-apply rule or put it in AGENTS.md. Cursor recommends keeping rules under 500 lines.

• If it's a procedure with steps, checks or a script ("cut a release", "add an API endpoint the way we do it"), make it a skill so it only takes up context when used.

• If your team uses more than one coding agent, prefer AGENTS.md over rules and skills in .agents/skills/ over .cursor/skills/, because other tools read those too. Our post on CLAUDE.md and AGENTS.md covers how to structure that file.

If you already have "Apply Intelligently" rules or custom slash commands, Cursor ships a built-in /migrate-to-skills skill (Cursor 2.4 and later). It converts rules that have no globs and no alwaysApply: true into skills, and turns user and workspace slash commands into skills with disable-model-invocation: true. Always-apply rules, glob rules and user rules stay as they are.

How to write a Cursor skill

The fastest start is the built-in /create-skill, which asks for a name and saves the folder for you. Writing one by hand takes a few minutes.

1. Create the folder

For a skill your whole team should get, create it in the repo:

mkdir -p .agents/skills/postgres-migration

mkdir -p .agents/skills/postgres-migration

mkdir -p .agents/skills/postgres-migration

Use .cursor/skills/ instead if only Cursor will ever read it. For a personal skill, use ~/.cursor/skills/.

2. Write SKILL.md

---
name: postgres-migration
description: Write and check PostgreSQL schema migrations for this repo. Use when adding or changing a file in prisma/migrations, or when a change adds a column, index or constraint.
paths: "prisma/migrations/**"
---

# Postgres migrations

## When to use
- Adding a column, index, constraint or table
- Editing an existing migration before it ships

## Steps
1. Generate the migration with `pnpm prisma migrate dev --create-only`.
2. If the SQL takes an ACCESS EXCLUSIVE lock on a large table, add
   `SET lock_timeout = '5s';` as the first statement.
3. Create indexes with `CREATE INDEX CONCURRENTLY`, alone in their own migration.
4. Run `scripts/check-migration.sh <file>` and fix anything it reports.

## Background
See `references/locking.md` for which statements take which locks

---
name: postgres-migration
description: Write and check PostgreSQL schema migrations for this repo. Use when adding or changing a file in prisma/migrations, or when a change adds a column, index or constraint.
paths: "prisma/migrations/**"
---

# Postgres migrations

## When to use
- Adding a column, index, constraint or table
- Editing an existing migration before it ships

## Steps
1. Generate the migration with `pnpm prisma migrate dev --create-only`.
2. If the SQL takes an ACCESS EXCLUSIVE lock on a large table, add
   `SET lock_timeout = '5s';` as the first statement.
3. Create indexes with `CREATE INDEX CONCURRENTLY`, alone in their own migration.
4. Run `scripts/check-migration.sh <file>` and fix anything it reports.

## Background
See `references/locking.md` for which statements take which locks

---
name: postgres-migration
description: Write and check PostgreSQL schema migrations for this repo. Use when adding or changing a file in prisma/migrations, or when a change adds a column, index or constraint.
paths: "prisma/migrations/**"
---

# Postgres migrations

## When to use
- Adding a column, index, constraint or table
- Editing an existing migration before it ships

## Steps
1. Generate the migration with `pnpm prisma migrate dev --create-only`.
2. If the SQL takes an ACCESS EXCLUSIVE lock on a large table, add
   `SET lock_timeout = '5s';` as the first statement.
3. Create indexes with `CREATE INDEX CONCURRENTLY`, alone in their own migration.
4. Run `scripts/check-migration.sh <file>` and fix anything it reports.

## Background
See `references/locking.md` for which statements take which locks

The parts that do the work:

• The description decides whether the agent ever loads the skill. Say what it does and when to use it, using words that will appear in real requests.

• Steps beat prose. Number them, name exact commands, and say what "done" looks like.

• Long background goes in references/, so it is read only when needed.

• Reference scripts with paths relative to the skill root. Cursor's docs ask that scripts be self-contained, with clear error messages, in any language your machine can run.

3. Test it

Start a new chat and ask for the task in plain words, without naming the skill. If the agent doesn't pick it up, rewrite the description before you touch the instructions. Then try /postgres-migration to check the steps themselves.

Installing skills from GitHub and the marketplace

To install a trusted skill folder manually:

1. Copy the whole folder into .agents/skills/ for a shared Cursor and Codex setup, or .cursor/skills/ for Cursor only. Keep any bundled scripts and references with SKILL.md.

2. Start a new Cursor chat and check Customize > Skills. Confirm the folder name matches the skill's name field.

3. Type / and select the skill to test it, then try a normal task prompt to check that its description triggers automatically.

The UI distributes shared skills through plugins. A plugin bundles skills with rules, MCP servers, hooks and commands, and you install it from Customize, choosing project or user scope.

Plugins come from:

• The official Cursor Marketplace, browsed from Customize.

• Customize > From GitHub Repository, for a repo that has a .cursor-plugin/marketplace.json.

• A team marketplace (Teams and Enterprise plans), where admins can set each plugin to off, on or required by default.

You can also publish one of your personal skills to your team's default marketplace from Customize > Skills.

Skills worth trying

Cursor ships its own skills, managed by Cursor and listed next to yours. Ones that help with day-to-day engineering: /create-skill, /create-rule, /migrate-to-skills, /split-to-prs (splits a large change into smaller PRs) and /loop (runs a prompt or skill on an interval).

Beyond those, these open-source skills exist today and use the standard SKILL.md format, so Cursor loads them from any of its skill folders:

The superpowers README lists a Cursor install: /add-plugin superpowers in Agent chat, or search for "superpowers" in the plugin marketplace. Anthropic's repo marks its skills as examples for demonstration and education, and some of them (the document skills) are source-available rather than open source, so read the license before you vendor one into a company repo. For longer lists, the community repo awesome-cursor-skills collects skills by category. Read any third-party SKILL.md and its scripts before installing it, since the agent will follow those instructions with your permissions.

For reviewing code before you push, cubic's skills (our product) run a local review, work through unresolved PR review comments, and loop review and fixes until the branch is clean. To install them for Cursor only:

npx @cubic-plugin/cubic-plugin install --to cursor --skills-only

npx @cubic-plugin/cubic-plugin install --to cursor --skills-only

npx @cubic-plugin/cubic-plugin install --to cursor --skills-only

In Cursor they show up as commands such as /cubic-run-review. The local review needs the cubic CLI installed and signed in, and the PR comment workflow needs the GitHub CLI; the skills docs list the setup, and the source is at mrge-io/skills. Our code review skill guide compares review skills across Cursor, Codex and Claude Code.

After the skill runs, inspect the diff and run the checks it names. For a practical checklist covering invented APIs, missing validation and security boundaries, see how to review AI-generated code. Bug Bench's Cursor page tracks bugs in AI-attributed code reviewed by cubic; its observational results reflect both model choice and the work teams assign to each model.

Using the same SKILL.md in Codex and Claude Code

The core format is shared, so one skill folder can serve all three agents. The difference is where each one looks:

.agents/skills/ covers Cursor and Codex. Claude Code's docs list .claude/skills/, which Cursor also reads. For all three agents, keep one canonical set in .agents/skills/ and expose it through symlinks under .claude/skills/, or reverse the arrangement and link into .agents/skills/ for Codex. Check discovery in each client so the copies do not drift.

Keep agent-specific fields in mind. name and description work everywhere, and disable-model-invocation exists in both Cursor and Claude Code. Cursor's paths field is Cursor's own; Codex turns off implicit invocation through an agents/openai.yaml file next to the skill instead. Test the skill in each agent you use. For Codex specifics, see our Codex skills guide.

FAQ

Do Cursor skills work in Cloud Agents?

Only skills in ~/.cursor/skills/ can sync to Cloud Agents, and only after you turn on "Sync Skills for Cloud Agents" under Settings > Agents. Synced skills stay private to you. Project skills in the repo travel with the code, and skills in ~/.agents/skills/ are not copied to Cloud Agents, remote SSH sessions or self-hosted workers.

Can I turn an existing Cursor rule into a skill?

Yes. Run /create-skill and ask the agent to convert the rule, check the result, then delete the old rule if you no longer need it. For many rules at once, /migrate-to-skills handles the eligible ones automatically.

Why isn't Cursor using my skill?

Check that the folder name matches the name field exactly and that the skill appears under Customize > Skills. If it's listed but never chosen, the description is usually too vague, or a paths pattern doesn't match the files you're working on. Calling it with / confirms the instructions work while you fix the description.

Is there a Cursor skills marketplace?

Cursor has an official plugin marketplace, and plugins are how skills are shared through the UI. Individual skills also live in GitHub repos, which you can copy into a skills folder or import as a plugin if the repo includes a .cursor-plugin/marketplace.json.