heydeer

Cursor skills: how Agent Skills work in Cursor

· · 9 min read

Cursor skills package a procedure the agent should follow, such as adding an API route the way your codebase does it, as a folder with a SKILL.md. Cursor’s docs list the fields; this guide works through two real skills and settles when to use a skill, a rule or a command.

Cursor skills are Agent Skills: folders containing a SKILL.md file with a name, a description and instructions. Cursor loads them from .cursor/skills/ and .agents/skills/ in your project and from ~/.cursor/skills/ and ~/.agents/skills/. The agent applies a skill when its description matches the task, and you can run one yourself by typing / and its name in Agent chat.

How Cursor agent skills work

When Cursor starts, it collects every skill it can find and shows the agent a list of names and descriptions. The agent decides from that list which skills fit the task and reads a skill’s full instructions only then; files the skill points to, such as a template or a script, are loaded when a step needs them. That is why a project can carry dozens of skills without filling the context window.

The format is the open Agent Skills standard, the same one Claude Code and Codex read. A skill written for one of them usually runs in Cursor unchanged, and Cursor goes out of its way to find them.

FolderScopeNotes
.agents/skills/ProjectShared with Codex and other agents
.cursor/skills/ProjectCursor’s own folder
~/.agents/skills/You, every projectStays on your machine
~/.cursor/skills/You, every projectThe one folder that can sync to Cloud Agents
.claude/skills/, .codex/skills/ and their ~/ versionsCompatibilityLoaded so existing Claude Code and Codex skills work

Which project folder to pick comes down to who else reads it. .agents/skills/ is shared with Codex and other Agent Skills tools, so a team on mixed editors writes each skill once. .cursor/skills/ keeps a skill to Cursor, which is sensible for skills that lean on Cursor-only fields.

Cursor walks skill folders recursively, so you can group skills in category folders such as .cursor/skills/shipping/release/; the skill’s name comes from the folder that holds SKILL.md, not the category. It also finds skill folders nested inside the repository, and scopes those to their directory:

my-monorepo/
├── .cursor/skills/
│   └── release/SKILL.md          available everywhere
└── apps/
    └── web/
        └── .cursor/skills/
            └── add-api-route/SKILL.md   only when working in apps/web/

Cloud Agents need one extra thought. Project skills travel with the repository. Personal skills in ~/.cursor/skills/ reach Cloud Agents only after you turn on Sync Skills for Cloud Agents under Settings → Agents, and ~/.agents/skills/ never leaves your machine. Automations, including ones set to Run as Me, use only the repository’s .cursor/skills/.

SKILL.md in Cursor: the fields that matter

Two fields are required. name uses lowercase letters, numbers and hyphens and must match the folder name. description says what the skill does and when to use it, and it is the only thing the agent reads when deciding whether to load the skill. A skill with a vague description is a skill the agent never picks.

Cursor adds optional fields on top of the standard:

  • paths takes glob patterns, as a list or a comma-separated string. The skill is only offered when the agent is reading or editing matching files. The older globs field still works as a fallback.
  • disable-model-invocation: true means the agent never applies the skill on its own; it runs only when you type /skill-name.
  • icon and color style the badge when the skill is used as a Custom Mode.
  • metadata holds any extra key-value pairs.

Next to SKILL.md, three optional folders follow the standard: scripts/ for code the agent runs, references/ for longer docs it reads on demand, and assets/ for templates and data. Steps refer to them by paths relative to the skill folder.

Creating a Cursor skill: a worked example

The fastest start is /create-skill in Agent chat: describe the workflow and Cursor’s built-in skill writes the folder and frontmatter for you. Writing the first one by hand is still worth it, because it shows what a good skill contains. Take a task every web team repeats: adding an API route that follows the house conventions.

mkdir -p apps/web/.cursor/skills/add-api-route/{references,scripts}
$EDITOR apps/web/.cursor/skills/add-api-route/SKILL.md
cp apps/web/src/app/api/projects/route.ts \
   apps/web/.cursor/skills/add-api-route/references/route-template.ts

Placing the skill in apps/web/.cursor/skills/ already scopes it to that app. The paths glob narrows it further, to the API folder:

---
name: add-api-route
description: Add or change an API route in apps/web. Use when creating an
  endpoint, a route handler or a server action that reads request data.
paths:
  - "apps/web/src/app/api/**"
---

# Add an API route

1. Copy references/route-template.ts into the new route folder and
   rename the handler. Every route exports named GET/POST functions,
   never a default export.
2. Parse the body and query with the zod schema next to the handler.
   Return 400 with the zod error for invalid input.
3. Call requireSession() from src/lib/auth.ts before reading the
   request. Routes under api/admin also call requireRole("admin").
4. Scope every database query by session.workspaceId.
5. Add a test in the same folder named route.test.ts that covers the
   happy path, invalid input and a request from another workspace.
6. Run scripts/check-routes.sh and fix anything it reports.

Every step names a real file or command. “Follow our conventions” gives the agent nothing to act on; “call requireSession() from src/lib/auth.ts before reading the request” does, and a reviewer can check it. The template in references/ does the work that paragraphs of style advice would otherwise try to do, and the last step hands the final check to a script, where it runs the same way every time.

To test it, run /add-api-route with a sentence about the endpoint you want. Then open a new chat and ask for “an endpoint that lists a workspace’s invoices” without naming the skill. If the agent doesn’t use it, rewrite the description with the words people actually type. Open Customize → Skills to confirm Cursor found the skill; project and plugin skills appear alongside rules under Agent Decides.

A skill that only runs when you ask

Some workflows shouldn’t start because a request happened to mention them. A release is the obvious case:

---
name: release
description: Cut a release. Bumps the version, writes the changelog entry
  and opens the release pull request.
disable-model-invocation: true
icon: rocket
color: orange
---

# Release

1. Confirm the working tree is clean and you are on main.
2. Run `pnpm changeset version` and show the version it chose.
   Stop and ask if it is a major bump.
3. Write the changelog entry from the merged pull requests since the
   last tag. Group them under Added, Changed and Fixed.
4. Create branch release/<version>, commit, and open a pull request
   titled "Release <version>". Do not tag or publish.

With disable-model-invocation: true, this behaves like a classic slash command: nothing happens until someone types /release. The icon and color show up if you run it as a Custom Mode (Option+Enter on Mac, Alt+Enter on Windows), which keeps the skill in context for the whole session instead of one message.

A Cursor skill is a folder with a SKILL.md in .cursor/skills or .agents/skills. Its description decides when the agent uses it, paths limits it to matching files, and disable-model-invocation makes it run only when someone types its name, which is the setting for releases, deploys and anything else that shouldn’t start on its own.

Installing community and built-in skills

Cursor ships a set of built-in skills you can run with /, and the agent uses some of them by itself when a request clearly matches. Besides /create-skill and /create-rule, the useful ones for day-to-day work include /review, which picks and runs a code-review agent, /split-to-prs for breaking a large change into smaller pull requests, and /migrate-to-skills, covered below.

Skills from GitHub reach Cursor in one of two ways. Cursor’s own route is plugins: official ones from the Cursor Marketplace, community ones listed on cursor.directory, or any repository with a .cursor-plugin/marketplace.json imported in Customize with From GitHub Repository. The skills arrive with the plugin. The other route is the open-source skills CLI, which copies a skill folder into .agents/skills/, where Cursor picks it up; the npx skills guide covers its commands. For a list of skills worth installing, nearly all of which run in Cursor, see the best Claude Code skills.

On Teams and Enterprise plans, a personal skill can be published from Customize → Skills to the team’s Default marketplace, where teammates install it. That is separate from syncing, which only makes your own skills available to your own Cloud Agents.

Cursor skills vs rules vs commands

This is where most setups go wrong: everything ends up as an always-on rule, and the agent carries three hundred lines of deploy instructions into a CSS fix. The distinction is when the text should be in context.

Cursor rules live in .cursor/rules/ as .mdc files (a plain .md there is ignored). Their frontmatter decides when they are included: alwaysApply: true puts a rule in every chat, globs attaches it when a matching file is in context, a description alone lets the agent judge relevance, and a rule with none of these is included only when you @-mention it. Cursor’s advice is to keep each rule under 500 lines, and to add one only when you notice the agent repeating a mistake. Here is the constraint half of the API route skill as a rule:

---
description: API route conventions
globs: apps/web/src/app/api/**
alwaysApply: false
---

- Named GET/POST exports, never a default export.
- Validate input with zod. Return 400 with the zod error.
- Every query is scoped by session.workspaceId.

Three lines that should hold whenever someone touches an API file, whether or not the task is “add a route.” The skill keeps the procedure: copy the template, write the test, run the check. The two work together; the rule keeps quick edits in line, and the skill does the full job when one is asked for.

Commands were Cursor’s first answer to reusable prompts: Markdown files in .cursor/commands/, run with /. A skill with disable-model-invocation: true does the same job and can bring scripts and templates, and Cursor’s built-in /migrate-to-skills converts user and workspace commands into exactly that. It also turns rules set to Apply Intelligently into ordinary skills, and leaves always-on and glob-scoped rules alone.

UseIn contextGood for
Project rule (.cursor/rules/*.mdc)Always, when a matching file is in context, or when the agent judges it relevantShort constraints: “named exports only”, “never edit dist/”
AGENTS.mdEvery conversation in the project or subdirectoryPlain-Markdown project instructions with no frontmatter
Skill (SKILL.md)When the agent picks it from its description, or when you type /nameMulti-step procedures, with templates and scripts beside them
Skill with disable-model-invocationOnly when you type /nameWorkflows that should never start on their own: releases, deploys

A quick way to sort an instruction: if it is one sentence that should always hold, make it a rule or a line in AGENTS.md. If it is a sequence of steps for one kind of task, make it a skill. If those steps have side effects you want to start yourself, add disable-model-invocation: true.

Using the same skills for code review

A skill like add-api-route describes how code in your repository should be written, which makes it equally useful for checking code someone else wrote. Because the format is shared, the skills in .agents/skills/ work beyond your editor. HeyDeer, an AI code review agent for GitHub pull requests, reads Agent Skills from .agents/skills, and a repository check can name the skills HeyDeer follows while it reviews each pull request. The conventions your Cursor agent follows while writing are the ones the review applies before merge.

Skills in .agents/skills are read by Cursor, Codex and HeyDeer alike. Writing a procedure once as an Agent Skill means the agent follows it while it writes code, and HeyDeer follows it when a repository check calls for it during pull request review.

HeyDeer also publishes free skills that run in Cursor, such as ci-audit, which measures your GitHub Actions runs and fixes what you pick; the rest are on the skills page. For the Codex side of the same format, see the Codex skills guide.

Sources

  1. Cursor Docs: Agent Skills
  2. Cursor Docs: Rules
  3. Cursor Help: Skills
  4. Cursor Docs: Plugins
  5. Agent Skills specification
  6. GitHub: vercel-labs/skills

Frequently asked questions

Where do Cursor skills go?

Cursor skills go in a folder named after the skill, containing a SKILL.md, inside .cursor/skills/ or .agents/skills/ in the project, or ~/.cursor/skills/ or ~/.agents/skills/ for skills you want in every project. Cursor also loads .claude/skills/ and .codex/skills/ for compatibility, and picks up skill folders nested anywhere in the repository.

How do I use a skill in Cursor?

A skill in Cursor runs when you type / in Agent chat and choose its name, which attaches it to that one message, or when you type @ and select it as context. The agent also applies skills on its own when a description matches the task. To keep a skill on for a whole session, use it as a Custom Mode with Option+Enter on Mac or Alt+Enter on Windows.

What is the difference between Cursor rules and skills?

Cursor rules are short guidelines included as context in every conversation or whenever a matching file is open, such as “use named exports.” Cursor skills are multi-step procedures the agent loads when a task calls for them, such as “add an API route: copy the template, validate input, write the test.” Use a rule for a constraint and a skill for a workflow.

How do I create a skill in Cursor?

A skill in Cursor is created by typing /create-skill in Agent chat and describing it, or by hand: make a folder in .cursor/skills/ named after the skill and add a SKILL.md with name and description frontmatter and the steps below it. The name must match the folder name and use lowercase letters, numbers and hyphens.

Can I use Claude Code or Codex skills in Cursor?

Claude Code and Codex skills work in Cursor because all three use the Agent Skills format. Cursor reads .agents/skills/, which Codex uses, and also loads .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/ for compatibility, so skills already in a repository appear without being copied.

How do I install community skills in Cursor?

Community skills reach Cursor in two ways. Plugins from the Cursor Marketplace, or from a GitHub repository with a .cursor-plugin/marketplace.json imported in Customize, bring their skills with them. The open-source skills CLI (npx skills add) copies a skill from GitHub into .agents/skills/, which Cursor loads.

Are Cursor commands replaced by skills?

Cursor commands can be converted to skills with the built-in /migrate-to-skills skill, available from Cursor 2.4. It turns each user and workspace command into a skill with disable-model-invocation: true, so it still runs only when you type its name, and it converts rules set to Apply Intelligently into ordinary skills.

Start with your first PR.

Free plan. No credit card required.

Get started free