Publisher: Skills Board. Published August 15, 2026. Last checked August 15, 2026.
Cursor skills are folders of instructions that Cursor's agent loads when a task matches what the folder is for. Each holds a SKILL.md file and, optionally, the scripts, references, and assets the task needs. Cursor's own documentation opens by calling Agent Skills an open standard for extending AI agents, not a Cursor feature, which is the most useful thing to know before you write one.
That matters because the file you write is the file the other agents read. The format was originally developed by Anthropic and released as an open standard, the specification lives at agentskills.io, and Cursor appears in the client showcase there alongside Claude Code, Codex, and a long list of others.
This page covers what Cursor actually reads, every directory it scans including the Claude and Codex ones, the frontmatter fields it documents and the ones it does not, how to add a skill in a few minutes, what carries over when the same file moves between agents, what a team decides once more than one person depends on a skill, and the parts Cursor has not documented.
In short
A Cursor skill is a directory containing a SKILL.md file: YAML frontmatter with a name and a description, then Markdown instructions. Cursor discovers skills from its skill directories when it starts, presents them to the agent, and the agent decides when each one is relevant based on context.
Cursor describes skills as portable, version-controlled, actionable, and progressive: any agent that supports the standard reads the same file, a skill is just files you can commit, it can bundle scripts, templates, and references the agent runs or reads with its own tools, and those resources load on demand rather than sitting in context.
There are two ways to reach a skill. The agent picks one implicitly when your request matches its description, which is why the description has to say what the skill does and when to use it, in the words someone would actually type. You can also invoke one explicitly by typing a forward slash in Agent chat and searching its name.
Cursor also ships built-in skills that appear alongside the ones you add, among them /create-skill for authoring a new one, /review and /review-security for code review, and /migrate-to-skills for converting rules and slash commands you already have. The full list is in Cursor's skills documentation.
Where Cursor looks for skills
Cursor loads skills from four of its own directories, two project-level and two user-level, and then, for compatibility, from four more that belong to other agents. That last part is the detail people coming from Claude Code or Codex do not expect, and it is documented rather than folklore.
| Location | Scope | What it is for |
|---|---|---|
| .agents/skills/ | Project | The vendor-neutral project directory. The same path Codex documents, so a repository that uses it serves both agents from one folder. |
| .cursor/skills/ | Project | Cursor's own project directory, next to .cursor/rules and the rest of the Cursor configuration checked into the repository. |
| ~/.agents/skills/ | User | Personal skills that apply to every project you open, in the vendor-neutral location. |
| ~/.cursor/skills/ | User | Personal skills in Cursor's own home directory, for anything you do not want to place in the shared one. |
| .claude/skills/ and ~/.claude/skills/ | Compatibility | Cursor documents loading skills from the Claude directories as well, so a repository already set up for Claude Code needs no second copy. |
| .codex/skills/ and ~/.codex/skills/ | Compatibility | Cursor lists these as the Codex directories, although OpenAI documents .agents/skills rather than .codex/skills. See the limits section below. |
Category folders are free. Cursor walks the skills root recursively and picks up any SKILL.md it finds, so you can group skills under shipping/, debugging/, or workflow/ subfolders. The category folder is organizational only: identity comes from the folder that directly contains SKILL.md.
Nested project directories are scoped automatically. A .cursor/skills/ or .agents/skills/ folder anywhere inside the repository is picked up, and Cursor documents that its skills surface only when the agent works with files inside that directory. In a monorepo, a skill in apps/web/.cursor/skills/ applies to apps/web while the repo-wide folder applies everywhere, with no frontmatter needed.
You can see what was actually found. Open Customize in the sidebar and go to Skills, where skills from a plugin or from the project appear alongside rules in the Agent Decides section, filterable by user, workspace, or team scope.
The SKILL.md fields Cursor documents
Two fields are required and the rest are optional. Two of the optional ones are Cursor's own additions to the standard, and they are the reason a Cursor skill can behave differently from the identical file read by another agent.
| Field | Required | What it does |
|---|---|---|
| name | Yes | The skill identifier. Lowercase letters, numbers, and hyphens only, and it has to match the parent folder name. The Agent Skills specification adds the constraints every client shares: at most 64 characters, no leading or trailing hyphen, no consecutive hyphens. |
| description | Yes | What the skill does and when to use it. Cursor states plainly that the agent uses this field to determine relevance, so it is the field that decides whether the skill ever fires. The specification caps it at 1024 characters. |
| paths | No | Glob patterns that scope the skill to matching files, as a comma-separated string or a list. When set, Cursor surfaces the skill only while the agent is reading or editing files that match, which keeps file-specific guidance out of unrelated work. |
| disable-model-invocation | No | Set it to true and the skill behaves like a traditional slash command: it enters context only when you type its name after a forward slash, and the agent will not apply it on its own. |
| metadata | No | An arbitrary key-value mapping. This one is in the Agent Skills specification too, which describes it as a map from string keys to string values that clients can use for properties the spec does not define. |
| globs | No | The legacy spelling of paths. Cursor documents that it is still accepted as a fallback for older skills, and that new skills should use paths instead. |
The body below the frontmatter is plain Markdown with no format restrictions, and all of it is read once the agent activates the skill. The specification recommends keeping SKILL.md under 500 lines and moving detailed reference material into separate files that load only when the instructions ask for them. Three of the six spec fields, license, compatibility, and allowed-tools, are absent from Cursor's table entirely, which the limits section below covers.
Skills are not rules, and Cursor is explicit about the split. Rule contents are included at the start of the model context; the 2.4 release note frames skills as better for dynamic context discovery and procedural how-to instructions. The built-in /migrate-to-skills converts eligible dynamic rules into skills, and slash commands into skills with disable-model-invocation set to true.
For the same field-by-field walkthrough on the OpenAI side, including the directories Codex scans and its separate agents/openai.yaml metadata file, see Codex skills: what they are and how to use them.
Cursor skills, Claude skills, and Codex skills: what actually transfers
The file transfers, and in Cursor's case more of the setup transfers than anywhere else, because Cursor is the only one of the three that documents reading the other two products' directories. What does not transfer is everything each product added on top of the standard.
| Area | Cursor | Claude Code | Codex |
|---|---|---|---|
| Project directory | .cursor/skills/ and .agents/skills/, plus .claude/skills/ and .codex/skills/ for compatibility | .claude/skills/, including nested ones below the working directory | .agents/skills/, scanned from the working directory up to the repository root |
| Personal directory | ~/.cursor/skills/ and ~/.agents/skills/, plus ~/.claude/skills/ and ~/.codex/skills/ | ~/.claude/skills/ | $HOME/.agents/skills |
| Explicit invocation | Type a forward slash in Agent chat and search the skill name | Type a forward slash and the skill name | /skills, or $ and the skill name |
| Turning off automatic use | disable-model-invocation: true in the SKILL.md frontmatter | Claude Code frontmatter fields for invocation control | allow_implicit_invocation in a separate agents/openai.yaml file |
| File scoping | paths globs in the frontmatter, or a nested project skills directory | Nested .claude/skills/ directories below the working directory | Directory position, since Codex scans from the working directory upward |
| Distribution | Agent Plugins and Cursor Plugins, from the marketplace or a team marketplace | Plugins and plugin marketplaces | Plugins published to the directory shared by ChatGPT and Codex, plus marketplace files |
Stay inside the specification and the file travels. It defines six frontmatter fields: name and description required, plus optional license, compatibility, metadata, and allowed-tools, the last marked experimental with support that varies. Anything outside that set is a product extension, so a skill that depends on paths or disable-model-invocation loses that behavior in an agent that does not read them.
Cursor reading the other directories removes a chore, not a difference. A repository set up for Claude Code works in Cursor with no second folder, but the reverse is not documented: neither Claude Code nor Codex documents reading .cursor/skills. For one folder that all three read, .agents/skills is the path Cursor and Codex both document, and Claude Code still needs .claude/skills or a symlink to it.
Portability is about the format, not the result. The same instructions can load in three products and still produce different work, because the tools, the sandboxing, the models, and the surrounding instructions differ. Test the skill in each agent your teammates actually run before you tell them it works there.
For the Claude side of the same standard, including the full frontmatter table and the surfaces skills run on, see Claude skills: what they are and how to use them.
How to add a skill to Cursor, step by step
There are three documented ways to end up with a skill Cursor can use: write the folder yourself, install a plugin that bundles skills, or ask a built-in skill to draft one for you. The manual path is worth learning first, because the other two produce the same thing on disk.
Decide which directory the skill belongs to
A skill everyone in the repository should have goes in .cursor/skills/ or .agents/skills/ at the project root. Pick .agents/skills/ if teammates also run Codex, since both products document it. A skill that is yours alone goes in ~/.cursor/skills/ or ~/.agents/skills/. A skill for one package in a monorepo goes in that package's own skills directory, where Cursor scopes it automatically.
Create the folder and the SKILL.md file
Make a directory named after the skill and put a SKILL.md file inside it. The frontmatter needs name and description. The name has to match the parent directory name and use lowercase letters, numbers, and hyphens, and the specification caps it at 64 characters with no leading, trailing, or consecutive hyphens.
Write the description for the trigger, not for the reader
Cursor states that the agent uses the description to determine relevance, so this field decides whether the skill ever fires. Say what it does and when to use it, in the words someone would actually type. A description that reads like a table of contents entry will not trigger.
Put the steps in the body and the bulk in separate files
The body is plain Markdown with no format restrictions. Keep SKILL.md under 500 lines, and move long reference material into references/, executable code into scripts/, and templates into assets/. Those load only when the instructions ask for them, which is the whole point of the format.
Scope it if it only applies to some files
Add a paths glob when the skill is about React components, Python style, or one package's conventions, and Cursor surfaces it only while the agent works with matching files. A skill placed in a nested project skills directory gets that scoping with no frontmatter at all.
Invoke it explicitly the first time
Type a forward slash in Agent chat and search for the skill name. Explicit invocation confirms Cursor found the folder and parsed the frontmatter. After that, leave it to the agent and see whether your description actually triggers on the requests you expected. Customize, then Skills, shows what Cursor discovered.
Or skip authoring entirely
The built-in /create-skill drafts a skill including its structure and SKILL.md, and /migrate-to-skills converts eligible dynamic rules and slash commands you already have. Installing a plugin from the Cursor Marketplace or a team marketplace brings its bundled skills with it, packaged under a skills/ directory with a SKILL.md per skill.
---
name: release-notes
description: Draft release notes from merged pull requests. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---
## Steps
1. List the merged pull requests since the last tag.
2. Group them into features, fixes, and internal changes.
3. Write one line per user-visible change, in plain language.
4. Leave internal refactors out unless they change behavior.
## Output
A Markdown section titled with the version and date.
How teams keep one recommendation across Cursor and other agents
Two problems hide behind one word. Distribution is getting the files onto each teammate's machine. Recommendation is knowing which skill to use for a task and why that one. Cursor has good answers for the first. The second is not a Cursor problem at all.
If every skill your team uses lives in a repository everyone works in, the answer is short: commit them to .cursor/skills/ or .agents/skills/ at the project root and Cursor picks them up with no extra tooling. That is the best setup for a single-repository team, and no shared library improves on it. Nothing here should talk you out of it.
It stops being enough when the skills come from other people's repositories, when they are useful in more than one repository, or when teammates run different agents. Cursor's answer to the first two is plugins: it supports the Agent Plugins standard alongside its own Cursor Plugin format and offers team marketplaces on Teams and Enterprise plans with per-plugin install modes. That covers packaging and rollout, but not teammates outside Cursor, because a Cursor Plugin is not what Claude Code or Codex installs.
The recommendation layer usually has no home at all. Which skill the team settled on, and why, ends up in a chat thread, a bookmark, or one person's memory. Skills Board is a shared library for that layer: the smaller set of skills your team recommends, in one searchable place, with the original source visible on every entry, and no assumption about which agent a teammate runs.
Paths
- Open the original source: Every saved skill records the repository and path it came from, so a teammate can read the SKILL.md before placing it.
- Copy an install command: For the teammates whose setup the command fits. It is one option among several, not the only path.
- Download a ZIP: The latest files available from the source at download time, for anyone who would rather place the folder themselves, in .cursor/skills or anywhere else Cursor scans.
- Connect Cursor over MCP: Add the Skills Board MCP endpoint to .cursor/mcp.json in a project or ~/.cursor/mcp.json to use it everywhere, then sign in from Cursor's MCP settings. The agent can search the same team library and retrieve install commands, and with the granted scopes save skills and organize collections. Sign-in happens in the browser, with no API key to copy.
Limits
- A saved skill is a team recommendation, not a security review, an approval, or a compatibility certification.
- Skills Board follows the latest version available from the saved source. It does not pin or preserve historical versions.
- The MCP connection cannot install or run a skill inside Cursor, and it cannot edit or delete saved team skills.
- It is not a replacement for a skills directory. The files still have to land somewhere Cursor scans, by whichever route each teammate prefers.
- The hosted product is free forever, the code is MIT licensed, and you can read or self-host all of it.
The operational version of this, with one canonical source and a tested install path per agent, is in Manage skills across Claude Code, Codex, and Cursor.
Limits and open questions
Some of what people expect to be documented is not. These are the gaps we found while reading Cursor's current documentation, written out rather than guessed at.
Precedence between the eight directories is not documented
Cursor lists four of its own skill directories and four compatibility ones, but does not say what happens when the same skill name appears in two of them. Claude Code documents a precedence order, and OpenAI documents that Codex does not merge same-named skills and may show both. Cursor documents neither, so treat duplicate names as untested.
Three optional specification fields are not documented for Cursor
The Agent Skills specification defines license, compatibility, metadata, and allowed-tools as optional, and marks allowed-tools experimental with support that varies between implementations. Cursor's frontmatter table documents metadata but not license, compatibility, or allowed-tools. Their behavior in Cursor is unverified.
Cursor lists .codex/skills, and OpenAI does not
Cursor names .codex/skills/ and ~/.codex/skills/ as the Codex compatibility directories. OpenAI documents .agents/skills from the working directory up to the repository root, $HOME/.agents/skills, and /etc/codex/skills. The overlap both products document is .agents/skills, so that is the safer choice for one folder serving Cursor and Codex.
There is no documented context budget for the skill list
Cursor describes progressive loading, but publishes no number for how much context the discovered skill list may take, or what happens when many skills are installed. OpenAI publishes a figure for Codex. Cursor does not, so how many skills you can keep installed is something you observe rather than look up.
The GitHub import path is documented through the rules flow
Cursor's skills page says you can import skills from GitHub through Customize, Rules, Add Rule, Remote Rule (Github). Its rules page describes that same flow as scanning the repository for .mdc files and importing them into .cursor/rules/imported/. How a SKILL.md folder ends up in a skills directory is not spelled out, so check the result in Customize, then Skills, before relying on it.
Only the editor and the CLI are named as surfaces
The 2.4 release note says Cursor supports Agent Skills in the editor and the CLI. The current Cloud Agents documentation does not mention skills, and neither does the agent overview page. Whether every Cursor surface loads a skill committed to a repository is not stated, so do not assume it.
Frequently asked questions
What is a Cursor skill?
A Cursor skill is a folder containing a SKILL.md file with YAML frontmatter and Markdown instructions. The frontmatter needs a name and a description. Cursor discovers skills from its skill directories at startup and presents them to the agent, which decides when each one is relevant. You can also invoke one by typing a forward slash in Agent chat.
Where do you put skills in Cursor?
Cursor loads project skills from .cursor/skills/ and .agents/skills/, and user-level skills from ~/.cursor/skills/ and ~/.agents/skills/. For compatibility it also loads from .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/. Nested skills directories inside the repository are picked up too, scoped to the files under them.
Does Cursor read Claude skills?
Yes. Cursor documents loading skills from the Claude and Codex directories for compatibility: .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/. The format is the same Agent Skills standard, so a repository already set up for Claude Code needs no second copy. Frontmatter fields specific to one product still do not carry over.
What is the difference between Cursor skills and Cursor rules?
Rules are declarative and always on: their contents enter the model context at the start. Skills load on demand, when the agent judges the description relevant or you invoke them. Cursor's 2.4 release note frames skills as better for dynamic context discovery and procedural how-to instructions, and ships /migrate-to-skills to convert eligible rules and slash commands.
How do you install a skill in Cursor?
Three documented paths. Create the folder yourself with a SKILL.md inside a directory Cursor scans. Install a plugin that bundles skills, from the Cursor Marketplace or a team marketplace. Or import from a GitHub repository through Customize, Rules, Add Rule, Remote Rule (Github). Check the result under Customize, then Skills.
Can you stop Cursor from using a skill automatically?
Yes. Set disable-model-invocation to true in the frontmatter and the skill behaves like a traditional slash command: it enters context only when you type its name after a forward slash. To narrow rather than disable automatic use, set a paths glob so the skill surfaces only on matching files.
How does a team share Cursor skills?
For one repository, commit them to .cursor/skills/ or .agents/skills/ and Cursor picks them up. Across repositories, Cursor distributes skills through plugins and team marketplaces on Teams and Enterprise plans. What neither covers is which skill the team recommends and why, especially when teammates run different agents, which is the layer a shared library like Skills Board holds.
Sources
- Cursor: Agent Skills: The skill directories including the Claude and Codex compatibility paths, nested and category folders, the frontmatter table, the optional directories, the built-in skills, the Customize view, the GitHub import path, and /migrate-to-skills.
- Cursor 2.4: Subagents, Skills, and Image Generation: The release that introduced Agent Skills in the Cursor editor and CLI, and the framing of skills against always-on rules.
- Cursor: Plugins: What plugins bundle, the Agent Plugins standard alongside Cursor Plugins, team marketplaces and their install modes, and managing skills from Customize.
- Cursor: Plugins reference: The skills format inside a plugin: one directory per skill under skills/, each with its own SKILL.md.
- Cursor: Rules: How rule contents enter the model context, and the Remote Rule (Github) import flow that scans a repository for .mdc files.
- Cursor: Customize Cursor: The Customize page, where skills, plugins, and MCP servers are managed at user, team, or workspace scope.
- Agent Skills specification: The six frontmatter fields and their constraints, the optional scripts, references, and assets directories, and the progressive disclosure and file-size recommendations.
- Agent Skills: overview and client showcase: The format as an open standard originally developed by Anthropic, and the showcase entry listing Cursor among the products that read it.
- Claude Code: skills documentation: Where Claude Code loads skills from, its precedence order, and nested project skills.
- OpenAI: build skills for ChatGPT and Codex: The directories Codex scans, its invocation syntax, its agents/openai.yaml file, and the published budget for the initial skill list.
Related resources
- AGENTS.md vs SKILL.md: two formats, two different jobs
- Claude skills: what they are and how to use them
- Codex skills: what they are and how to use them
- Manage skills across Claude Code, Codex, and Cursor
- How to share AI agent skills with your team
- A shared MCP skill library for teams
Originally published at skillsboard.sh/cursor-skills.
Top comments (0)