Why your Cursor skill isn't showing up

Cursor fills three lists at different times: Customize → Skills shows what it discovered, the / menu shows what the current chat can invoke, and the model's catalog is the name and description injected into that chat's context. Most "my skill disappeared" reports come from that split, so name which list is missing the skill first. A Cursor skill is a folder containing a SKILL.md file: a short description in the frontmatter and instructions in the body, discovered from a few project and user roots.

Run Cursor → About Cursor in the editor, or agent --version in the CLI, before comparing your build with a forum report. The skill scanner changed in 3.17 (hidden directories) and 3.25 (warning icons and same-name rows); Cursor 3.27 is the newest build on the release-notes page as of 27 October 2026.

Checked against Cursor's documentation, release notes and CLI changelog on 27 October 2026.

Status, 27 October 2026: the catalog is fixed when a chat starts; a skill added to a running chat needs a new chat (staff reply, #165124, 8 July 2026, Cursor 3.10.20).

Which list is missing the skill?#

A skill can be in the first row but not the second, or the second but not the third (disable-model-invocation: true). One added after the chat began can be in neither list.

Where Cursor looks for skills#

Cursor's skills reference lists four primary roots and four compatibility roots. Each skill is the folder that contains a SKILL.md; category folders above it are only organization.

A .cursor/skills/ folder inside a subdirectory is discovered too, and is automatically scoped to that subtree. In a monorepo, apps/web/.cursor/skills/deploy-web/ is only surfaced when the agent works with files under apps/web/. That is a feature until you are at the repo root wondering where the skill went. Two roots with the same skill name are two skills to Cursor: 3.25 shows separate / rows.

Before 3.17 (August 2026), the scanner also descended into hidden directories inside ~/.claude/skills and loaded duplicates, which is how unrelated skills reached the initial context (#160677, fixed 14 August 2026). Built-in skills live in ~/.cursor/skills-cursor; Cursor re-seeds them on update by design (staff, May 2026).

The file is there, but the skill is not#

It is not shaped like a skill#

The folder must contain SKILL.md; a plain my-skill.md in .cursor/skills/ is not a skill, and Cursor expects each skill in its own folder, so a loose SKILL.md at that root is not a normal layout. The frontmatter needs name and description; name must be lowercase letters, numbers and hyphens, and must match the folder. Without a description the model has nothing to match, and on 3.27 and later a Cloud Agent run names a skill whose description is missing or whose file it could not read. The field list is in the skills reference.

It is in a root Cursor does not read#

.agent/skills (no s) is not a Cursor root, and neither is ~/.cursor/skill. The user roots are ~/.agents/skills/ and ~/.cursor/skills/; ~/.cursor/rules belongs to the rules system, but whether your build reads it is version-dependent (the rules guide covers that check). A skill in .claude/skills/ or ~/.codex/skills/ depends on the third-party import. In May 2026, staff said turning off Include third-party Plugins, Skills and other configs stops the .claude/, .codex/ and .agents/ roots entirely (#160677, 14 May 2026). A home-directory symlink was a separate bug, fixed in 2.5 (#149693, February 2026), and the CLI followed them from 22 June 2026; a later 2.5.22 report disagreed, so copy the folder if yours is missing.

`paths` scoped it to other files#

paths (or the older globs field) limits a skill to matching files. It is only surfaced when the agent works with one. A skill scoped to **/*.tsx will not be offered to the model for a Markdown-only task, and a wrong pattern keeps it out of every task's context. Remove the field for one run.

The frontmatter hid it from the side you are checking#

disable-model-invocation: true keeps a skill out of automatic selection; only /skill-name includes it (skills reference). A generator can add it silently, which is why a skill can sit in the / menu but be absent from the agent's available list (#158131, 17 April 2026). In the CLI, user-invocable: false is the opposite: no / entry, still available to the model (CLI changelog, 6 July 2026). For every turn, pick it in / and press Option+Enter (Alt+Enter on Windows) to make it a Custom Mode; a plain /skill-name attaches once (prompting docs).

The chat started before the skill existed#

The catalog is snapshotted at chat start. A skill added to an open chat needs a new chat; there is no /reload-skills. Reload Window only if / is still missing there, which staff called a slash-menu race (#165124, 8 July 2026). Cursor 3.26 fixed the empty / picker after editing an earlier message (release notes).

You are on a different surface#

• Remote SSH: staff said in April 2026 that the editor does not read the local ~/.cursor/skills/ in an SSH window; use a project .cursor/skills/ in the remote workspace. One later report on macOS → native Windows found the project .cursor/skills/ and .agents/skills/ folders also failed; test it on your build (#158377, 18 April 2026, Cursor 3.1.15).
• Cloud Agents: only ~/.cursor/skills/ syncs; ~/.agents/skills/ and unsynced local skills are not copied to Cloud Agents, Agents Window remote SSH sessions, or self-hosted workers (skills reference). Automation runs do not load synced skills.
• Plugins: a plugin's skills appear under Customize when the plugin is installed. If they are missing, check the plugin's scope and restart; plugin skills were a known broken area in 2.5 and 2.6, with fixes in 2.6 and 2.6.18 for Windows (#152988, March 2026).

It is listed, but the agent does not use it#

Discovery is not selection. Once the catalog is in the prompt, the model chooses by name and description, so a listed skill can lose to a better-matching one, a rule, or its own plan.

A description that says what the skill does but not when to use it is the common cause. "Deployment helpers" is a label; "Use when deploying to staging or production, or when the user mentions releases" is a trigger.

Too many skills also make selection worse: every discovered skill contributes its name and description to the initial context, including compatibility roots and plugins. The context ring's Skills row shows that cost (prompting docs); if it is large and mostly other agents' skills, trim the roots or use disable-model-invocation on the ones you only invoke by hand.

If the skill worked and then stopped in a long chat, compaction is the likely cause: Cursor's docs do not say what survives a summary, and the general mechanism means a skill body read mid-session can be summarized away. The compaction guide covers the general mechanics, not a Cursor guarantee.

Check what actually loaded#

Do not ask the model "what skills do you have?" It sees the injected catalog, not the loader or the settings list, so its answer is not evidence of what Cursor found.

Use these instead:

• Customize → Skills lists discovered skills and their scope. In 3.25 and later, its warning icon covers names over 64 characters, a name/folder mismatch, descriptions over 1,024 characters, and bodies over about 5,000 tokens (release notes; CLI changelog). It is the editor's only built-in view that shows a skill Cursor found but no chat is using.
• The / menu in a new chat shows what that chat can invoke. If the skill is in Customize but not here, start a new chat; if it is still absent, reload the window.
• The CLI's /skills browser lists discovered skills and their warnings; agent --version tells you which CLI you are testing. Since 8 October 2026 it shows a warning count. Older builds had a gap where / scanned only .cursor/skills while the agent context loaded ~/.agents/skills; staff said on 23 March 2026 that the fix would land in the next CLI release (#155358).
• A Cloud Agent run on 3.27 and later names a skill whose SKILL.md cannot be read, has invalid frontmatter, or lacks a description.

A canary is the one test that ties a name to a body. Make a throwaway skill with a marker only it contains:

.cursor/skills/canary/SKILL.md
---
name: canary
description: Use only when the user types /canary or asks for the canary test.
---
Begin your reply with SKILL-CANARY-741, then say "canary loaded".

Start a new chat, type /canary, and send it. If the marker appears, the file was discovered and its body reached the model on that turn. If /canary is missing, the problem is discovery; if it runs but the marker does not appear, delivery or the model is the problem. Neither result proves a normal task.

Subagents: what they inherit, and how to turn them off#

A skill is instructions the main agent loads; a subagent is a separate agent with its own context window, launched for a job. Cursor's built-in skills create both (/create-skill, /create-subagent), which is why Customize confuses them.

Cursor's built-in subagents are Explore (codebase search) and Browser (browser control via MCP tools). Custom ones are Markdown files in .cursor/agents/ or ~/.cursor/agents/, with Claude and Codex locations as compatibility roots; .cursor/ wins when names collide (subagents reference).

What they inherit. A subagent starts with its own context window and the prompt the parent writes; it does not see the prior conversation. It inherits the parent's tools, including MCP tools. model: inherit is the default, and readonly: true removes edits and state-changing shell commands. In the CLI, subagents also inherit credentials, rules and approval policy (CLI changelog, March 2026). The editor docs do not say whether User Rules or skills reach a subagent; a 2.4 pre-release report found AGENTS.md but not User Rules, and staff did not confirm it (#148987, 15 January 2026). Put what the subagent must know in its agent file or launch prompt.

How to turn them off. There is no single global switch; a Cursor staff reply said so in April 2026 (#157018, 9 April 2026). What exists:

• Explore only: Settings → Agents → Subagents → Explore subagent model → Disable. It covers only Explore, not Browser or general-purpose subagents; the CLI exposes it under /config (CLI changelog, 11 August 2026).
• A hard block: a subagentStart hook that returns permission: "deny" stops the launch; permission: "ask" is treated as deny (hooks reference). Match on the subagent type to block only Explore or Browser. The hooks guide covers loading and failure behaviour.
• A soft block: a User Rule such as "Never use subagents. Do all work in the main agent context." Staff call it a working workaround, not a hard block: the model usually follows it (same thread, 4 May 2026).
• Custom subagents only: remove the file from .cursor/agents/ or ~/.cursor/agents/, or switch it off in Customize → Subagents.

Where to go next#

• Cursor guides — the rest of the set.
• Does Cursor read AGENTS.md? — when the instruction file is not a skill at all.
• Why your Cursor rule isn't applied — when the thing competing with the skill is a rule.
• Context compaction — when the skill worked until the chat was summarized.
• Why your Cursor hook doesn't fire — when the subagentStart block is the part failing.