Cursor troubleshooting

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

  1. Open Customize, then Skills (or Rules). If the item is listed, skip to step 5.
  2. Check the path. A skill lives at .cursor/skills/<name>/SKILL.md (or under .agents/skills/ or ~/.cursor/skills/). A project rule is an .mdc file in .cursor/rules/.
  3. Check the name. The name field must match the skill's folder and use only lowercase letters, numbers and hyphens.
  4. 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.
  5. 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.
  6. Reload. Open the command palette, run Developer: Reload Window, or restart Cursor.
  7. 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.md must 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: true is set. That makes the skill manual-only on purpose.
  • A paths pattern 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 globs pattern does not match the files in context.
  • You expected it to change Tab completions. Rules only apply to the Agent. A .cursorrules file 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.md cannot be read, has frontmatter that does not parse, or has no description.

The Agent cannot see some project files

  • Files listed in .cursorignore are hidden from the Agent, codebase search and @ mentions.
  • Patterns in .gitignore can 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

  1. Open the command palette: Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows and Linux.
  2. Run Developer: Reload Window. Your project stays open. Quitting and reopening Cursor works too.
  3. 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.

.cursor/skills/hello-skill/SKILL.md
---
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?".

.cursor/rules/rules-check.mdc
---
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?

Cursor discovers skills when it starts. If a new skill does not appear under Customize, then Skills, run Developer: Reload Window from the command palette or restart Cursor, then open a new Agent chat.

Why does my skill work when I type its name but not on its own?

The Agent decides from the description, so a vague or missing description is the usual cause. Also check that disable-model-invocation is not set to true, and that any paths patterns match the files you are working on.

Why does a skill work on my machine but not in Cloud Agents?

Personal skills in ~/.cursor/skills/ stay on your machine until you turn on Sync Skills for Cloud Agents under Settings, then Agents. Skills in ~/.agents/skills/ are never copied to Cloud Agents. For a skill every run should have, including automations, commit it to the repository's .cursor/skills/ folder.

Why can't the Agent see some of my project files?

Files listed in .cursorignore are blocked from the Agent, codebase search and @ mentions, and .gitignore patterns can also hide files. Check both, then open the command palette and run Reindex. You can also attach a file directly by typing @ followed by its name.

Should I reinstall Cursor if my skills stop loading?

Usually not. Reinstalling does not change the skill and rule files Cursor reads. Fix the folder, the frontmatter or the description, reload the window, and test in a new chat first.

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.