CursorRulesLevel 3: Workflows

When Should a Cursor Rule Be a Skill Instead?

If something is needed only sometimes, make it a skill. Cursor's course puts it simply: rules are for what the agent should always know, and skills are for what it can do when asked. A skill is a folder containing a SKILL.md file, and you can run it by typing / and its name, or let Agent load it when relevant.

Prompt to copy
/create-skill

Create a project skill called [skill-name] in .cursor/skills/[skill-name]/SKILL.md.

The description should say what it does and when to use it, including the words I'd actually use to ask for it.

Steps:
1. [first step, with the exact command]
2. [next step]
3. [how to verify success]
4. [what to report back]

If this should never run unless I ask for it, set disable-model-invocation: true.
Ruleswhat it should always know
  • Loaded every conversation
  • Always uses context
  • Always-on conventions
Skillswhat it can do when asked
  • Loaded when relevant
  • Full cost only when used
  • Specialized workflows
From Cursor's Customizing agents course.

Try it now

  1. 1Pick a procedure you've explained to Agent more than once, and type /create-skill in the input.
  2. 2Check that name in the frontmatter matches the folder name exactly, using lowercase letters, numbers and hyphens.
  3. 3Type / in a new chat and pick your skill. It worked if it follows the steps without further explanation. Commit it so your team has it.

Use it when

Multi-step procedures you repeat: deploying, opening a PR, updating dependencies, running a test-first workflow. It's also the right home for domain knowledge that matters only in part of the repo. Check your long rule files for anything you need only occasionally.

Skip it when

Conventions the agent must follow on every edit, such as your test framework, belong in a rule, because a skill might not load. Don't use a custom subagent either for something this simple. Cursor's docs recommend a skill for single-purpose tasks that finish in one shot.

Why it works

An always-on rule costs context in every conversation, whether or not it's relevant. A skill's description sits in the context, and the full instructions load only when needed. So a long deploy procedure costs little until you deploy. Skills can also bundle scripts/, references/ and assets/ folders. Cursor discovers them at startup from .cursor/skills/ or .agents/skills/ in your project, or the same folders in your home directory. It also loads .claude/skills/ and .codex/skills/ for compatibility.

Example

Say a rule file has 200 lines on deploying to staging, and it loads in every chat. You move those lines to .cursor/skills/deploy-staging/SKILL.md, with the description "Deploys to staging. Use when I ask to deploy or ship to staging." You add disable-model-invocation: true because a deploy should only ever happen on request. Your always-on context shrinks, and /deploy-staging runs the same steps every time.

Going further

Run /migrate-to-skills to convert eligible dynamic rules and slash commands automatically. In a monorepo, a skill inside apps/web/.cursor/skills/ surfaces only when the agent works with files under apps/web/, or use the paths field for the same effect. To keep a skill active throughout a session, choose it from the / menu and press Option+Enter (Alt+Enter on Windows) for a Custom Mode. Personal skills in ~/.cursor/skills/ don't reach Cloud Agents unless you turn on Sync Skills for Cloud Agents, and ~/.agents/skills/ isn't copied at all.

Common mistakes

  • A name that doesn't match its folder. Cursor requires them to match.
  • A vague description. Agent uses it to decide relevance, so "deployment helper" may never trigger.
  • Putting a must-follow convention in a skill, then wondering why it was skipped.
  • Leaving model invocation on for a skill with real side effects, such as deploying.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course