Cursor Skills or Rules Not Loading? How to Reload and Fix Them
When a Cursor skill or rule is not being used, the cause is usually a file in the wrong place, frontmatter Cursor cannot read, or a description too vague for the Agent to match. Check the file against the list below, reload the window, then test it in a new Agent chat.
Last updated By Gizmolab
The seven-step fix
- Open Customize, then Skills (or Rules). If the item is listed, skip to step 5.
- Check the path. A skill lives at
.cursor/skills/<name>/SKILL.md(or under.agents/skills/or~/.cursor/skills/). A project rule is an.mdcfile in.cursor/rules/. - Check the name. The
namefield must match the skill's folder and use only lowercase letters, numbers and hyphens. - Check the frontmatter. It starts with
---on the very first line and ends with another---. Put quotes around any value that contains a colon followed by a space. - Check the description. It should say what the skill or rule does and when to use it. Without one, the Agent is unlikely to pick it on its own.
- Reload. Open the command palette, run
Developer: Reload Window, or restart Cursor. - Test in a new Agent chat. Type
/and the skill's name first. If that works, try a normal request that matches the description.
Symptoms and what to check
The skill is not listed under Customize, then Skills
SKILL.mdmust be inside its own folder. A file saved directly in.cursor/skills/is not a skill.- The file must be named
SKILL.md, in a folder Cursor scans:.cursor/skills/,.agents/skills/, their~/versions, or the.claude/and.codex/equivalents. - Cursor discovers skills when it starts. Reload the window after adding one.
The skill runs with /name but the Agent never picks it
- The description is missing or too vague. Say what it does and when, in the words you type.
disable-model-invocation: trueis set. That makes the skill manual-only on purpose.- A
pathspattern does not match the files you are working on, so the skill is not offered. - The skill sits in a package folder, such as
apps/web/.cursor/skills/, so it only applies to files in that package.
A rule is never applied
- The file ends in
.md. Project rules in.cursor/rules/must be.mdc. - The rule type is Apply Intelligently but there is no description.
- The rule is Apply to Specific Files and the
globspattern does not match the files in context. - You expected it to change Tab completions. Rules only apply to the Agent. A
.cursorrulesfile is legacy: move it into a project rule.
It works locally but not in Cloud Agents
- Personal skills in
~/.cursor/skills/reach Cloud Agents only after you turn on Sync Skills for Cloud Agents (Settings, then Agents, under Context and Tools). - Skills in
~/.agents/skills/are never copied to Cloud Agents, remote SSH sessions or self-hosted workers. - Automations do not load synced personal skills. Commit the skill to the repo's
.cursor/skills/instead. - A Cloud Agent run shows a warning naming any skill whose
SKILL.mdcannot be read, has frontmatter that does not parse, or has no description.
The Agent cannot see some project files
- Files listed in
.cursorignoreare hidden from the Agent, codebase search and @ mentions. - Patterns in
.gitignorecan also keep the Agent from finding files. - Run Reindex from the command palette, or attach the file directly by typing
@and its name.
How to reload Cursor
- Open the command palette: Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows and Linux.
- Run
Developer: Reload Window. Your project stays open. Quitting and reopening Cursor works too. - Start a new Agent chat, so an earlier conversation does not muddy the test.
You do not need to reinstall Cursor. If a reload does not help, the problem is in the file, so go back through the checklist.
Compare with files that are known to work
Add these two files, reload, and test them. If they load and yours does not, the difference is in your file. The rule makes loading easy to see: every answer ends with the same line. Delete both when you are done.
---
name: hello-skill
description: Lists the commands that run this project's tests. Use when the user asks how to run the tests.
---
# Hello skill
Read package.json and list every script that runs tests, one per line, with a short note on what each one covers.Test with /hello-skill, then by asking "how do I run the tests?".
---
alwaysApply: true
---
- End every answer with the line "Project rules loaded."Ask the Agent anything. If the last line is missing, project rules are not loading.
Check that the fix really worked
- Re-run the same prompt you used before the fix. Change the file or the prompt, never both at once.
- Use a small, real task where the skill's steps are easy to see.
- Check that the Agent follows the steps in order and returns the output format you wrote.
- If it still drifts, make the description or the limits more specific rather than longer.
FAQ
Do I need to restart Cursor after adding a new skill?
Why does my skill work when I type its name but not on its own?
Why does a skill work on my machine but not in Cloud Agents?
Why can't the Agent see some of my project files?
Should I reinstall Cursor if my skills stop loading?
Related guides
- Cursor skills
What a Cursor skill is, where Cursor looks for SKILL.md files, and how the Agent uses them.
- How to create a Cursor skill
Build a skill step by step, from the folder and frontmatter to testing it in Agent chat.
- 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.
- 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.