How to use your Claude Code skills in Cursor

Leave them where they are. Cursor's skills documentation says that "for compatibility" it also loads skills from .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/, so a skill folder you already use in Claude Code is discovered in Cursor without being moved, copied or converted. Two things then decide whether it actually works: the name field, which Cursor requires and expects to match the parent folder name, and the frontmatter beyond name and description, where Cursor documents a different and much shorter list of fields than Claude Code does.

This guide covers the port in that order: where Cursor looks, the one field to fix, what carries and what does not, subagents, and what to check when a skill still does not show up.

#Where does Cursor look for skills?

Cursor documents eight locations plus four compatibility ones, and a Claude Code skill lands in the last group.

A skill is a folder with a SKILL.md inside it, and Cursor allows optional scripts/, references/ and assets/ directories beside that file, which is the same layout Claude Code uses. Cursor also walks its skill roots recursively, so a skill in a category subfolder is still found, and a .cursor/skills/ or .agents/skills/ folder inside a nested project directory is picked up and scoped to that directory.

#Should you move the folder to .agents/skills?

Not if you still want the skill in Claude Code from the same checkout. Claude Code's skills documentation lists its load paths as .claude/skills/<skill-name>/SKILL.md at the project, personal, nested, enterprise and --add-dir levels, plus a plugin's own skills/ folder and the ~/.claude/skills/synced/ folder it downloads claude.ai skills into. .agents/skills/ is not among them.

So the two tools overlap in exactly one place, and it is the directory your skills are already in:

• Keep it in .claude/skills/ when the skill has to work in Claude Code and Cursor. Both vendors document reading it.
• Use .agents/skills/ for a skill in a project where Cursor, and other agents that read that convention, are the audience. Our own where agent skills go guide has the directory table for the wider set of tools.

Treat Claude Code support for .agents/skills/ as undocumented rather than absent, and do not build a repository layout on it.

#Which field has to change?

One, and it is the field most Claude Code skills never bothered to set.

That difference is the whole porting job for most skills. A skill folder called pdf-report/ whose SKILL.md carries no name works in Claude Code, which fills the name in from the folder. Cursor documents name as required, so set it explicitly, and set it to the folder name:

---
name: pdf-report
description: Generate the monthly PDF report from the sales CSV. Use when asked for the monthly report or a PDF summary of sales.
---

Two details worth getting right while you are in the file:

• Characters. Cursor restricts name to lowercase letters, numbers and hyphens. An underscore or a capital letter in a folder name is a rename rather than an edit, because the field has to match the folder.
• The description does the triggering in both tools. Cursor says the agent "is presented with available skills and decides when they are relevant based on context", and Claude Code loads a listing of names and descriptions for the same purpose. A description that names the task and the trigger phrases earns its place in both.

#What carries across, and what does not?

Cursor's skills page documents seven frontmatter fields. Claude Code documents more than twenty. The overlap is the useful part of this table, and the third column is the part that bites.

Claude Code states that it "ignores unrecognized fields without reporting an error", so Cursor's icon and color are safe to leave in a shared skill. The reverse is where to be careful: Cursor's documentation does not say what it does with a field it does not document, so do not assume a Claude Code extra is either honoured or harmlessly dropped. Check the skill's behaviour in Cursor before you rely on it.

Three of those extras matter enough to call out, because they are the ones people build real guardrails from:

• allowed-tools and disallowed-tools are how a Claude Code skill narrows what the model may do while it is active. Cursor documents no equivalent on a skill, so a skill that was safe in Claude Code because of its tool list is not safe in Cursor for the same reason. Cursor's readonly field on a subagent is the nearest documented control, and it is a different mechanism on a different object.
• hooks register in Claude Code when the skill is invoked and stay for the session. Nothing in Cursor's skills documentation does this.
• model, effort, context and agent change how Claude Code runs the skill. Cursor documents a model field on subagents, not on skills.

#How do you invoke a ported skill in Cursor?

Three ways, from Cursor's documentation:

1. Automatically. The agent is shown the available skills and decides when one is relevant from context, the same shape as Claude Code's automatic invocation.
2. Manually, with /. Type / in Agent chat and pick the skill. Cursor says a skill invoked this way attaches to one message, which is narrower than Claude Code's behaviour of adding the skill's content to the conversation for the rest of the turn and beyond.
3. For a whole session, as a Custom Mode. Option+Enter on a Mac, Alt+Enter on Windows. This is the route with no Claude Code counterpart, and it is where icon and color are used.

If you only ever want explicit invocation, disable-model-invocation: true means the same thing in both tools: the skill is included only when invoked on purpose.

#What about subagents?

Cursor reads those from Claude Code's directory too. It documents .cursor/agents/ and .claude/agents/, labelled "Claude compatibility", and .codex/agents/ for the project, with ~/.cursor/agents/, ~/.claude/agents/ and ~/.codex/agents/ for the user. Project subagents override user subagents, and when the same name appears in several locations, ".cursor/ takes precedence over .claude/ or .codex/".

The fields Cursor documents for a subagent are narrower than its skills list is long:

Invocation is automatic by description, explicit with /name or by naming the subagent in a sentence, and parallel when the agent issues several Task calls at once. If you are weighing whether a job belongs in a skill or a subagent in the first place, skills vs subagents vs plugins vs MCP is the comparison, and sub-agents mastery covers the delegation patterns.

#A skill does not appear in Cursor. What now?

Work down this list before you start editing the body of the skill.

1. Is name set, lowercase, and equal to the folder name? This is the documented requirement Claude Code does not enforce, so it is the first thing to check on any skill that came from there.
2. Is the file called SKILL.md, inside a folder, inside one of the roots above? A loose .md file in a skills root is not a skill in either tool.
3. Does a paths pattern exclude the file you are working on? Both tools use paths to limit when a skill loads automatically. A pattern that fits your Claude Code layout may not fit the files you have open in Cursor.
4. Is the name taken? Cursor gives .cursor/ precedence over .claude/ and .codex/ for subagents with the same name. Avoid duplicate names across roots rather than working out which copy won.
5. Are you expecting it in a Cloud Agent? Only ~/.cursor/skills/ syncs there, and only with Sync Skills for Cloud Agents enabled. Project skills and ~/.agents/skills/ stay on your machine.

#Before you share a skill folder between tools

Two habits are worth keeping, and both are about the fact that a skill is instructions a model will follow.

A skill you did not write is code you did not read. Run it past the checklist in how to audit a SKILL.md before you put somebody else's skill folder in a directory that two agents both load automatically, and remember that ClawDocx vets none of them. The blast radius of a shared .claude/skills/ is larger than of either tool alone, because both products pick it up.

A skill that leans on allowed-tools for safety is not portable, however well it ports in every other respect. Keep the guardrail where it is enforced: in Claude Code's frontmatter for Claude Code, and in Cursor's own permission and subagent controls for Cursor. The Cursor platform hub and the Claude Code platform hub track what each product documents as it changes.