A Cursor skill that never triggers almost always fails one of four checks. **Location:** the skill must be a folder containing `SKILL.md` inside a documented skills directory, such as `.cursor/skills/` or `.agents/skills/` in the project, or `~/.cursor/skills/` for user-level skills. **Frontmatter:** valid YAML with the required `name` and `description`, and `name` must match the folder name. **Description:** it has to say what the skill does and when to use it, because that's what the agent matches on. **Scope:** a `paths` glob, a nested directory, or `disable-model-invocation: true` can keep it out of automatic use on purpose.
Who this is for
You wrote a `SKILL.md`, and the agent keeps ignoring it, or you can't find it in the list. This card follows the order Cursor itself uses: discover the skill, parse it, decide whether it's relevant.
Symptom card
| Symptom | Most likely check that failed |
|---|---|
| Skill not listed under Customize → Skills | Location or frontmatter |
| Listed, but `/skill-name` finds nothing | `name` doesn't match folder, or invalid characters in `name` |
| Listed, works with `/`, never picked automatically | Description too vague, `paths` too narrow, or `disable-model-invocation: true` |
| Works in one package, not another | Skill sits in a nested `.cursor/skills/` and is scoped to that directory |
| Works locally, missing in Cloud Agents | User-level skill not synced (see below) |
| Agent follows a rule instead | An always-on rule covers the same job |
Checklist: path → frontmatter → description → scope
1. Path
Cursor discovers skills from these directories (per Cursor's skills docs):
| Location | Scope |
|---|---|
| `.agents/skills/` | Project |
| `.cursor/skills/` | Project |
| `~/.agents/skills/` | User (local machine) |
| `~/.cursor/skills/` | User (local machine) |
It also loads from `.claude/skills/`, `.codex/skills/`, `~/.claude/skills/`, and `~/.codex/skills/` for compatibility.
Each skill is a folder with a `SKILL.md` inside it: `.cursor/skills/my-skill/SKILL.md`. A loose `.cursor/skills/my-skill.md` doesn't match that shape. Category subfolders are fine (Cursor walks the skills root recursively), and the skill's identity comes from the folder that holds `SKILL.md`.
Cloud Agents: only `~/.cursor/skills/` can be synced, via Settings → Agents → Sync Skills for Cloud Agents. `~/.agents/skills/` and unsynced local skills don't reach Cloud Agents. Project skills committed to the repo travel with the repo.
2. Frontmatter
---
name: release-notes
description: Draft release notes from merged PRs. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---| Field | Required | Gotcha |
|---|---|---|
| `name` | Yes | Lowercase letters, numbers, and hyphens only. Must match the parent folder name. |
| `description` | Yes | Used by the agent to decide relevance. |
| `paths` | No | Globs. When set, the skill only surfaces for matching files. |
| `disable-model-invocation` | No | `true` means `/skill-name` only; never automatic. |
Other optional fields exist (`icon`, `color`, `metadata`). Older skills may use `globs`, which is still accepted as a fallback for `paths`. Frontmatter has to be valid YAML at the very top of the file: an unclosed quote, a tab, or a missing `---` line breaks it.
3. Description
The description is the trigger. Write it the way a task would be phrased:
| Weak | Strong |
|---|---|
| "Helps with docs." | "Draft release notes from merged PRs. Use when asked for release notes, a changelog, or what shipped." |
| "Database utilities." | "Write and review SQL migrations for Postgres. Use when adding a table, column, or index." |
Name the job, the inputs, and the moment to use it.
4. Scope and collisions
- `paths` too narrow: the skill hides unless matching files are in play. Unset it for a general skill.
- Nested skill directory: a `.cursor/skills/` inside `apps/web/` is scoped to files under `apps/web/` automatically.
- Manual-only: `disable-model-invocation: true` is intentional; remove it if you want automatic use.
- Duplicate names: two folders with the same skill name across directories make it unclear which one you're editing. Keep names unique.
- Rule shadowing: an always-apply rule that already describes the procedure can steer the agent away from the skill. Keep rules to short constraints and put the procedure in the skill.
Test loop
- Open Customize → Skills and confirm the skill appears.
- Type `/` in Agent chat and invoke it by name. If this works, discovery and parsing are fine, and the problem is the description or scope.
- Start a fresh chat and give a throwaway task phrased like the description. Check whether the agent uses the skill.
- If it doesn't, rewrite the description and repeat step 3. Change one thing at a time.
Soft next step
Run the four checks on the one skill that's been ignored, starting with the folder shape and the `name` match. For a free starter desk with a working skill to copy, begin at /free. When you want a full set of skills, roles, and `AGENTS.md` files that already pass these checks, the Operator Pack ($47) has them. Cheat Sheet for the skim checklist mindset.