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
- Pick one job you repeat, such as fixing a failing test or preparing a release.
- Create
.cursor/skills/<skill-name>/, using lowercase letters, numbers and hyphens. - Add
SKILL.mdwith aname(the same as the folder) and adescription(what it does and when to use it). - Write the instructions: when to use it, the steps, the output and the limits.
- Open Customize, then Skills, to confirm Cursor found it.
- 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
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.
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.
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.
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
---
name: fix-failing-test
description: Helps with tests.
---Specific: says what and when
---
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.
---Write the instructions
Below the frontmatter, write plain markdown. There is no required structure, but these four sections keep a skill predictable:
| Section | What to write | Example line |
|---|---|---|
| When to use | The situation the skill is for, and a nearby job it is not for. | Not for flaky tests that pass on retry. |
| Steps | What to read first, then the actions in order. | Run only the failing test and read the full error. |
| Output | The shape of the answer, so every run is easy to review. | Cause, fix, and the commands you ran. |
| Limits | What must not change, and when to stop and ask. | Do not weaken an assertion to make a test pass. |
The finished skill:
---
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.Add scope, scripts or references (optional)
| Add | When it helps |
|---|---|
paths | Only offer the skill when the Agent works with matching files, for example "app/api/**/*.ts". |
disable-model-invocation: true | Only 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. |
.cursor/skills/release-notes/
├── SKILL.md
├── scripts/
│ └── collect-commits.sh
└── references/
└── style-guide.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.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.
---
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?
How long should a SKILL.md file be?
Can a Cursor skill run scripts?
How do I stop Cursor from using a skill automatically?
Can I convert an existing Cursor rule into a skill?
Related guides
- Cursor skills
What a Cursor skill is, where Cursor looks for SKILL.md files, and how the Agent uses them.
- Cursor skill examples
Complete SKILL.md files for edits, debugging, refactors, reviews and planning.
- Cursor AI rules
Project rules in .cursor/rules, the four rule types, .mdc templates and AGENTS.md.
- How to reload Cursor skills
What to check when a skill or rule does not load, and how to reload Cursor safely.
- Cursor skills for Web3 developers
SKILL.md examples for wallet flows, Solidity reviews, testnet deploys and Anchor programs.
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.