Cursor skill tutorial

How to Create a Cursor Skill

To create a Cursor skill, make a folder in .cursor/skills/ named after the skill, add a SKILL.md file with a name and a description in its YAML frontmatter, and write the steps the Agent should follow underneath. Or type /create-skill in Agent chat and Cursor builds the files for you.

Last updated By Gizmolab

The short version

  1. Pick one job you repeat, such as fixing a failing test or preparing a release.
  2. Create .cursor/skills/<skill-name>/, using lowercase letters, numbers and hyphens.
  3. Add SKILL.md with a name (the same as the folder) and a description (what it does and when to use it).
  4. Write the instructions: when to use it, the steps, the output and the limits.
  5. Open Customize, then Skills, to confirm Cursor found it.
  6. Test it with /skill-name, then with a normal request that should trigger it.

Option 1: let Cursor create it with /create-skill

Cursor ships a built-in skill for this. Type /create-skill in Agent chat and describe the job, for example "a skill that fixes failing tests: run only the failing test, find the cause, make the smallest fix". It walks you through naming, structuring and saving the skill.

Then review the SKILL.md it wrote against steps 3 and 4 below. The description and the limits are the parts most worth tightening by hand.

Option 2: create a Cursor skill by hand

1

Pick one job

A skill should do one repeatable job well. Good first skills: fixing a failing test, writing a PR description, adding an API route the way your codebase does it, preparing a release, or a Web3 task such as a testnet deploy.

Avoid one skill that plans, edits, debugs and reviews. The Agent has a harder time knowing when to use it, and you have a harder time telling whether it helps.

2

Create the skill folder

Use .cursor/skills/ for a skill the whole project should have, or ~/.cursor/skills/ for one only you need in every project. The folder name becomes the skill's name.

Terminal
mkdir -p .cursor/skills/fix-failing-test
  • Lowercase letters, numbers and hyphens only, 1 to 64 characters.
  • No hyphen at the start or end, and never two hyphens in a row.
  • The name field in SKILL.md must match the folder name exactly.
3

Write the frontmatter

The frontmatter is the YAML block at the top of SKILL.md. The description matters most: the Agent reads it to decide whether the skill fits your request, so say what the skill does and when to use it, in the words people actually type.

Too vague: the Agent rarely picks it

SKILL.md
---
name: fix-failing-test
description: Helps with tests.
---

Specific: says what and when

SKILL.md
---
name: fix-failing-test
description: Finds and fixes the cause of a failing test. Use when a test fails, CI is red, or the user pastes a test error or stack trace.
---
4

Write the instructions

Below the frontmatter, write plain markdown. There is no required structure, but these four sections keep a skill predictable:

Sections of a SKILL.md body
SectionWhat to writeExample line
When to useThe situation the skill is for, and a nearby job it is not for.Not for flaky tests that pass on retry.
StepsWhat to read first, then the actions in order.Run only the failing test and read the full error.
OutputThe shape of the answer, so every run is easy to review.Cause, fix, and the commands you ran.
LimitsWhat must not change, and when to stop and ask.Do not weaken an assertion to make a test pass.

The finished skill:

.cursor/skills/fix-failing-test/SKILL.md
---
name: fix-failing-test
description: Finds and fixes the cause of a failing test. Use when a test fails, CI is red, or the user pastes a test error or stack trace.
---

# Fix a failing test

## When to use

- A unit or integration test fails locally or in CI.
- Not for writing new tests. Not for flaky tests that pass on retry: report those instead.

## Steps

1. Run only the failing test and read the full error. Use the test command from package.json.
2. Read the test and the code it exercises before changing anything.
3. Decide whether the test or the code is wrong, and say why in one or two sentences.
4. Make the smallest change that fixes the cause. Never weaken or delete an assertion to make it pass.
5. Run the failing test again, then the rest of that test file.

## Output

- Cause: one or two sentences.
- Fix: the files you changed and why.
- Checked: the commands you ran and their result.

## Limits

- Do not refactor unrelated code.
- Do not update snapshots unless the new output is intended, and say so if you do.
- If the cause is outside this repository (an API, an environment variable, a dependency), stop and explain instead of patching around it.
5

Add scope, scripts or references (optional)

Optional skill settings and folders
AddWhen it helps
pathsOnly offer the skill when the Agent works with matching files, for example "app/api/**/*.ts".
disable-model-invocation: trueOnly run the skill when you type /skill-name. Use it for skills with side effects, like releases.
scripts/Executable files the Agent can run. Reference them by relative path from the skill folder.
references/Longer docs the Agent reads only when needed, which keeps SKILL.md short.
assets/Templates, config files or data the skill uses.
Folder layout
.cursor/skills/release-notes/
├── SKILL.md
├── scripts/
│   └── collect-commits.sh
└── references/
    └── style-guide.md
.cursor/skills/release-notes/SKILL.md
---
name: release-notes
description: Drafts release notes from the commits since the last git tag. Use when preparing a release.
disable-model-invocation: true
---

# Release notes

1. Run scripts/collect-commits.sh to list the commits since the last tag.
2. Group them under Added, Changed and Fixed, following references/style-guide.md.
3. Leave out internal refactors and dependency bumps unless they change behavior.
4. Show the draft. Do not create the tag or publish anything.
6

Test it

Test on a task you already understand, so you can judge the result. A skill is working when all of these hold:

  • The skill appears under Customize, then Skills.
  • Typing /skill-name in a new Agent chat runs it.
  • A normal request that matches the description makes the Agent use it without being asked.
  • The Agent follows the steps in order and returns the output format you wrote.
  • It stays inside the limits. If it does not, make that limit more specific.

Not listed, or never picked? See How to reload Cursor skills.

Fill-in SKILL.md template

Copy this, replace everything in angle brackets, and save it as .cursor/skills/<skill-name>/SKILL.md. For finished examples, see Cursor skill examples.

.cursor/skills/<skill-name>/SKILL.md
---
name: <skill-name>
description: <What the skill does, in one sentence>. Use when <the situations or words that should trigger it>.
---

# <Skill title>

## When to use

- <The situation this skill is for>
- Not for <a nearby job it should not handle>

## Steps

1. <What to read or check first>
2. <The main action>
3. <How to check the result>

## Output

- <The shape of the answer: summary, files changed, checks run>

## Limits

- <What the Agent must not change>
- <When to stop and ask instead of guessing>

Common mistakes

Saving SKILL.md directly in .cursor/skills/. Every skill needs its own folder.

A name that does not match the folder, or that uses capitals or spaces.

A vague description such as "Helps with code", so the Agent never picks the skill.

One skill that plans, edits, debugs and reviews. Split it into one skill per job.

A very long SKILL.md. Keep it under 500 lines and move detail into references/.

API keys or private keys in a skill. Skills are plain files, often committed: read secrets from environment variables.

Turn an existing rule or command into a skill

Type /migrate-to-skills in Agent chat. It converts rules set to Apply Intelligently (no alwaysApply and no globs) into skills, and turns slash commands into skills with disable-model-invocation: true so they still only run when you call them. Rules that always apply or match file patterns are left as rules.

Rules are covered in Cursor AI rules.

FAQ

What should the description of a Cursor skill say?

Say what the skill does and when to use it, in the words a user would actually type. The Agent reads the description to decide whether a skill is relevant, so "Helps with tests" is rarely picked, while "Finds and fixes the cause of a failing test. Use when a test fails or CI is red" is. The Agent Skills format allows up to 1024 characters.

How long should a SKILL.md file be?

Short enough to read in one go. The Agent Skills specification recommends keeping SKILL.md under 500 lines and the instructions under about 5,000 tokens. Move long reference material into a references/ folder, which the Agent only loads when it needs it.

Can a Cursor skill run scripts?

Yes. Put executable files in a scripts/ folder inside the skill and reference them from SKILL.md by relative path, such as scripts/deploy.sh. The Agent reads the instructions and runs the script when the skill is used. Bash, Python and JavaScript are common choices, and the script needs whatever runtime it uses to be installed on the machine.

How do I stop Cursor from using a skill automatically?

Add disable-model-invocation: true to the skill's frontmatter. The skill is then only used when you type /skill-name in Agent chat, which suits skills with side effects such as deploys or releases.

Can I convert an existing Cursor rule into a skill?

Yes. Type /migrate-to-skills in Agent chat to convert rules set to Apply Intelligently, and your slash commands, into skills in .cursor/skills/. For any other rule, type /create-skill and ask the Agent to turn it into a skill, for example "turn @my-rule into a skill", then delete the old rule if you no longer need it.

Related guides

Using a different tool? See Claude Code skills, OpenClaw skills or the AI skills hub.

Sources

This guide was checked against the official documentation on 5 November 2026. Cursor changes quickly, so when something here differs from the docs, the docs win.