What Is a Cursor Skill? The Plain-English Guide (Plus When You Actually Need One)

By Rakshit Yadav (@yadavrakshit60)•Oct 2026•8 min read

Short answer: a Cursor skill is a folder at .cursor/skills/<name>/SKILL.md containing a short YAML frontmatter block (a name and a description) followed by plain-markdown instructions for one job — writing Stripe webhooks, running an on-page SEO audit, scaffolding a Next.js route. Cursor's agent reads every skill's description up front, and only loads the full body into context when your current task actually matches that description. That's the whole mechanism: cheap to keep around, expensive only when used. If you're deciding whether you need one at all, or how it's different from a rule or a slash command, this is the plain-English version — the comparison tables live elsewhere on this site, linked below.

What a Cursor skill actually is

Strip away the tooling and a skill is two things: a small routing signal (the description field) and a body of instructions that only gets read when that signal matches. Here's the minimum shape:

---
name: stripe-webhooks
description: Use when implementing or debugging Stripe webhook handlers, signature verification, or idempotency keys.
---

# Stripe Webhook Handling

1. Verify the signature with `stripe.webhooks.constructEvent` before touching the payload...
2. Store the event ID and check it against prior events before processing, to guarantee idempotency...

That's it — no special runtime, no compiled format. The file is plain markdown, which is why the shape is portable across the current crop of AI coding agents (the agentskills.io open spec documents this same name/description/body layout). Cursor's agent scans the description fields of every installed skill against your prompt and the task at hand; when one matches closely enough, it opens that file and reads the instructions before acting. A skill you never trigger costs nothing beyond the one-line description sitting in the agent's working set — which is the entire reason skills exist as a separate primitive instead of just pasting everything into one giant rules file.

Why not just put it all in a Cursor rule?

Because a rule is always on. Cursor rules (.cursor/rules/*.mdc, or a .cursorrules file) load into every relevant request based on glob scoping or an "always apply" flag — there's no judgment call about whether the content is needed right now. That's correct for things that are always true: "we use pnpm, not npm," "this repo is Next.js App Router, not Pages," "never touch /legacy." It's wasteful for things that are only true sometimes: the full procedure for rotating a Stripe webhook secret, or the checklist for writing FAQ schema markup, isn't relevant to 95% of your prompts, and stuffing it into an always-on rule means paying that context cost on every single turn whether you need it or not.

A skill flips that trade: it costs nothing until the agent decides the current task matches its description, at which point the whole procedure loads in. The practical split most teams land on is a short, always-on rule for the handful of facts every request needs, plus a stack of skills for everything that's situational. The full Cursor Rules vs Skills comparison covers the file-location and precedence details if you're wiring both into the same repo.

Skill vs. rule vs. slash command, in one paragraph each

  • A rule is a constraint, not an instruction to perform a task — "always use zod for validation," "never commit .env files." It's read passively on every matching request.
  • A skill is a procedure — "here's how to debug a Stripe webhook signature mismatch." It's read actively, only when the agent judges the current task needs it.
  • A slash command (/ship, /launch) is something you type to kick off a known workflow. It doesn't wait for the agent to decide relevance — you're deciding it by typing the command — and a command frequently points at a skill internally to do the actual work, the same way a recipe card points at a technique.

If you're choosing between a rule and a skill for a specific piece of content, the Cursor Rules vs Skills decision guide walks through the actual decision tree rather than just the definitions.

When you actually need a skill (and when you don't)

Reach for a skill when:

  • The procedure is long enough that it would bloat an always-on rule if it lived there instead — a multi-step Stripe integration checklist, a full on-page SEO audit process, a database migration runbook.
  • The task is recurring but not universal — most sessions in the repo won't touch Stripe webhooks, but the ones that do need the same procedure every time.
  • You want the same procedure to be triggerable by description-matching alone, without a human remembering to type a specific command.

Skip the skill (use a rule instead) when:

  • The content is a constraint that applies to every request regardless of topic — package manager, folder structure, tone of voice for copy.
  • The content is short enough that the always-on cost is negligible (a one-line "use pnpm" doesn't need a skill wrapper).

Skip the skill (use a command instead) when:

  • You want a specific, repeatable workflow to run exactly on your trigger, not on the agent's judgment call about relevance — e.g., /ship running your whole pre-deploy checklist in a fixed order.

Quick reference: skill vs. rule vs. command

Cursor skillCursor ruleSlash command
File location.cursor/skills/<name>/SKILL.md.cursor/rules/*.mdc or .cursorrules.cursor/commands/<name>.md
Loaded whenAgent matches task to descriptionAlways, or on glob/file-type matchYou type it
Best forA procedure used sometimesA fact true on every requestA fixed workflow you trigger on purpose
Context cost when unused~Zero (only the description sits in context)Paid on every matching requestZero
Typical lengthA page or moreA few lines to a short paragraphA short checklist or a pointer to a skill

Common mistakes when writing a first skill

A few failure modes show up repeatedly in skill files that don't get triggered when they should:

  • The description is written for a human, not a matcher. "Stripe integration helper" reads fine to a person skimming a file list, but it gives the agent almost nothing to match against. "Use when implementing or debugging Stripe webhook handlers, signature verification, or idempotency keys" gives it three concrete phrases to match a real prompt against.
  • The skill tries to cover too much ground. One SKILL.md for "backend stuff" will rarely match precisely enough to trigger, and when it does, half the body is irrelevant to the actual task. Narrower skills with narrower descriptions match more reliably.
  • The body stays abstract instead of giving exact commands. A skill that says "verify the webhook signature properly" instead of showing the actual stripe.webhooks.constructEvent call isn't saving the agent any more effort than a rule would — the value of a skill is in the concrete, copy-pasteable detail it can afford to include because it only loads when needed.
  • Nobody ever tests whether the skill actually triggers. Write the skill, then run a prompt that should obviously match its description and check (via Cursor's own debug/trace output, where available) that the skill actually loaded. A skill that silently never triggers is dead weight.

Writing your first SKILL.md

  1. Name the job, not the technology. stripe-webhook-handling beats stripe — a sharper name makes the description-matching more precise, since the agent is partly matching against intent, not just keywords.
  2. Write the description like a search query a future prompt would actually produce. "Use when implementing or debugging Stripe webhook handlers, signature verification, or idempotency keys" gives the matcher concrete trigger phrases. A vague description ("Stripe stuff") under-triggers.
  3. Put the procedure in the body as concrete, ordered steps — code snippets, exact commands, the actual gotchas you've hit before. This is the part that only costs context when it's genuinely needed, so there's no reason to keep it terse.
  4. Keep one skill to one job. A skill that tries to cover Stripe, SendGrid, and Twilio in one file makes the description vague and the body unfocused. Split it into three.
  5. Drop it in .cursor/skills/<name>/SKILL.md. Cursor discovers skills in that directory automatically — no registration step beyond the file existing with valid frontmatter.

FAQ

Is a Cursor skill the same file format as a Claude Code skill? Yes — both follow the same name/description/markdown-body shape under the open agentskills.io spec, which is why a well-written SKILL.md can be dropped into .cursor/skills/ and .claude/skills/ unchanged. Cursor Skills vs Claude Code Skills covers the small differences in how each editor loads and matches them.

Do I need to register a skill somewhere, or does Cursor just find it? Cursor scans .cursor/skills/ for valid SKILL.md files automatically — there's no separate registry or config entry to add.

What happens if two skills have overlapping descriptions? The agent still has to pick one (or neither) based on which description the task matches more closely, so overlapping descriptions make matching less reliable. Keep each skill's job narrow enough that its description doesn't overlap another's.

Can a slash command use a skill? Yes — a command is a trigger a human types; it's common for a command's own instructions to explicitly point at a skill ("run the on-page-seo skill against this URL") so the command's fixed workflow delegates the detailed procedure to the skill that already has it written out.

Where can I see real SKILL.md examples instead of a toy one? The Cursor skills catalog lists 61 production skills across engineering and marketing, each with its own SKILL.md you can open and read.

Related Tools & Agents

🛠️ Free Tool: kit-picker🤖 Agent: tech-lead⚡ Command: /shipSkill: project-conventionsSkill: stripe-paymentsSkill: on-page-seo

Browse all 61 production skills

Every skill in this guide's examples is a real, installable file — see the full engineering and marketing catalog.

Browse the skills catalog →