Cursor Skills vs Claude Code Skills: What Actually Differs

Cursor skills (.cursor/skills/<name>/SKILL.md) and Claude Code skills (.claude/skills/<name>/SKILL.md) use the same shape — a short YAML frontmatter block with a name and description, followed by a markdown body the agent loads on demand. The folder, the exact fields a client reads, and what else is sitting alongside the skill in each tool's ecosystem are where they diverge. Last updated 2026-10-30 by Rakshit Yadav.

Verdict in one line

The file format is close enough to copy-paste; the ecosystem around it is not. A Cursor SKILL.md and a Claude Code SKILL.md both open with YAML frontmatter and a markdown playbook, so moving the body across tools is usually a find-and-replace on paths. What doesn't carry over cleanly is how each tool decides to open that file: Claude Code skills sit alongside subagents and hooks that can route to them explicitly, while Cursor skills are more often paired with rules and commands. Pick based on which tool you actually run day to day, not on which skill format looks cleaner on paper.

Skill definition format, side by side

Cursor skillClaude Code skill
File.cursor/skills/<name>/SKILL.md.claude/skills/<name>/SKILL.md
FrontmatterYAML block: at minimum a name and a description the agent reads before deciding whether to open the bodyYAML block: a name and a description field, read the same way — the description is what Claude sees first, the body only loads on match
BodyPlain markdown — instructions, examples, gotchas, as long as neededPlain markdown, same freedom; can also be invoked explicitly from a slash command or referenced by name from a subagent definition
Who else reads itUsually just the main agent loop, often alongside a .cursor/rules/*.mdc file for hard bansThe main agent, any subagent whose own file points at it, and commands that name it directly

Discovery and invocation differences

Both tools use the same core trick: keep the body out of context until it's needed, and use the description as the cheap signal for "is this relevant right now." The difference is in how many ways a skill can get triggered. A Claude Code skill can load because the main agent's own judgment matched the description, because a slash command names it directly, or because a subagent's definition points at it as part of that role's standard toolkit — so the same skill can serve a human typing a request and an automated multi-agent pipeline without being rewritten. A Cursor skill mostly relies on the one path: the agent's own read of the description against the current task, with rules doing the harder job of forcing something to always apply.

Practically, this means a Claude Code skill library benefits more from being explicit and name-addressable — write descriptions assuming a command or a subagent might cite the skill by its folder name, not just assuming the main loop will stumble onto it. A Cursor skill library should lean harder on the description text alone, since that's the only thing deciding whether it loads.

Portability and migration

Moving a skill's content between the two tools is usually painless: the markdown body — the actual instructions, examples and gotchas — doesn't reference the tool it runs in, so it copies over unchanged. What breaks on a straight copy: the folder path (.cursor/skills vs .claude/skills), any relative links to other project files that assume one tool's directory layout, and any mention inside the skill of calling a command or subagent by name, since those are named differently (or don't exist at all) on the other side. A skill that only teaches a standard — "webhook handlers must be idempotent," "always derive the tenant from the session" — ports in minutes. A skill written as glue between a specific command and a specific subagent needs to be re-wired, not just moved.

Which to standardize on for a solo founder

Standardize on whichever tool is your actual daily driver, and keep the skill bodies as tool-agnostic as you can so the eventual port is cheap. If you run Claude Code day to day, lean into the extra invocation paths — let subagents and commands name your skills directly instead of hoping the main loop finds them. If you run Cursor, put more weight on the description field itself, since it's doing all the discovery work alone, and keep a .cursor/rules file for anything that must never be skipped rather than trying to force a skill to behave like a hard rule. Running both tools on the same repo is common enough that it's worth keeping skill bodies free of tool-specific command or subagent references, so the same knowledge file can live in both folders with only the frontmatter path changed.

Verdict table

ScenarioPick
Daily driver is Claude Code, want skills wired into subagents and commandsClaude Code skill, name-addressable
Daily driver is Cursor, skill needs to stand on its ownCursor skill, description-heavy
Knowledge must never be skipped, not just "usually loaded"A rule (Cursor) or CLAUDE.md (Claude Code), not a skill on either side — see Rules vs Skills vs Commands
Running both tools on one repoWrite the body once, tool-agnostic; keep two thin SKILL.md files, one per folder
Skill needs live data (a database, an API), not just instructionsNeither — add an MCP server, see Skills vs MCP

Related pages

Frequently asked questions

  • Is a Cursor SKILL.md the same file as a Claude Code SKILL.md?
    Structurally yes — both are YAML frontmatter (name, description) plus a markdown body, loaded on demand rather than always-on. They live in different folders (.cursor/skills vs .claude/skills) and are discovered by different clients, so a file written for one needs its path changed, and any tool-specific references rewritten, before it works in the other.
  • Can I use the same skill content in both Cursor and Claude Code?
    Yes, if the skill is pure knowledge — a standard, a checklist, a gotcha list with no references to a specific command or subagent by name. Keep two copies of the thin SKILL.md frontmatter, one in each folder, pointing at the same instructional body.
  • Which has more ways to trigger a skill, Cursor or Claude Code?
    Claude Code, because skills there can be reached by the main agent's own judgment, by a slash command naming it directly, or by a subagent definition pointing at it as part of that role's toolkit. Cursor skills rely mainly on the agent matching the description against the current task.
  • Should I migrate an existing Cursor skill library to Claude Code, or vice versa?
    Only if you're actually switching your daily driver. If you run both tools, it's cheaper to keep the instructional bodies tool-agnostic and maintain two small SKILL.md shells than to fully migrate one direction.
  • Is a skill the right place for something that must always apply?
    No, on either side. A skill is loaded on demand and can be skipped if its description doesn't match. Hard requirements belong in a Cursor rule or in Claude Code's CLAUDE.md, both of which load unconditionally.

Ship skills for the tool you actually use

AgenticKit installs a matching skill set for Claude Code or Cursor in one command, so you're not hand-porting SKILL.md files between folders.