Guide
Cursor skills: where Cursor reads SKILL.md
Cursor loads Agent Skills from a few folders, and it reads the same SKILL.md format as Claude Code. This page lists the folders and fields from Cursor's own docs, how to install a skill, and which free skills to try first.
Where Cursor looks
| Scope | Folders Cursor reads |
|---|---|
| This project | .agents/skills/ and .cursor/skills/ |
| Every project (your machine) | ~/.agents/skills/ and ~/.cursor/skills/ |
| Compatibility folders | .claude/skills/, .codex/skills/, ~/.claude/skills/, ~/.codex/skills/ |
Cursor walks skill folders recursively and discovers nested .cursor/skills/ or .agents/skills/ folders inside a repo, scoped to their directory. Each skill is a folder with a SKILL.md, and optional scripts/, references/ and assets/. Cursor finds skills at startup, so start a new session after adding one.
This matches the Cursor row in ProSkills' install table: project .agents/skills/ (or .cursor/skills/), user ~/.cursor/skills/.
Fields Cursor supports
| Field | What it does in Cursor |
|---|---|
name | Required. Lowercase letters, numbers and hyphens. Must match the parent folder name. |
description | Required. What the skill does and when to use it. The agent uses it to judge relevance. |
paths | Glob patterns that limit when the skill is surfaced. The older globs field is still accepted. |
disable-model-invocation | When true, the skill runs only when you invoke it with /skill-name. |
metadata | Arbitrary key-value pairs. |
icon, color | Badge icon and colour when the skill is used as a Custom Mode. |
The Cursor page does not say how it treats license, compatibility or allowed-tools. We have not verified that, so we make no claim about them. The full open format is in the format reference.
Install a skill in Cursor
- Pick a skill folder (the one holding
SKILL.md). - Copy it to
.agents/skills/in your project, or~/.agents/skills/for every project. - Start a new Cursor session so it is discovered.
- Open Customize, then Skills, to confirm it is listed. Or type / in Agent chat and search its name.
Or let the CLI place it. It writes one folder and nothing else:
npx proskills-cli add taste-core --agent cursor
.agents/skills/ is read by Cursor, Codex and Gemini CLI alike, so one copy there covers all three. More install routes are in the install guide.
Free skills that work in Cursor
Every one is a standard SKILL.md folder. The score is the scanner's, computed from the shipped files.
| Skill | Use it when | Scan |
|---|---|---|
| Character Bible | The user creates or reuses an AI character | 100/100 |
| Wardrobe & Sets | The user needs outfit or location ideas | 100/100 |
| Taste Core | The user builds or restyles any UI | 100/100 |
| Hyperframes Starter | The user wants a video built from HTML | 100/100 |
| Humanizer | The user writes or edits any prose | 100/100 |
| Hook Lab | The user writes the first line of a post | 100/100 |
| Grill Me | The user shares a plan or asks to build something non-trivial | 100/100 |
| PR Describer | The user opens or describes a pull request | 100/100 |
| AGENTS.md Architect | The user writes, rewrites or audits CLAUDE.md, AGENTS.md or rules files | 100/100 |
| Analytics SQL | The user writes a report, metric or analytics query | 100/100 |
| Dockerfile Doctor | The user writes or fixes a Dockerfile | 100/100 |
| Prospect Brief | The user names a lead or company | 100/100 |
| CRUD Scaffold | The user needs a data-backed internal tool | 100/100 |
Scan before you install
A skill is instructions your agent follows, so check one from someone else before you copy it in. Paste it into the scanner, or run it over the folders Cursor reads:
npx proskills-cli scan .agents/skills .cursor/skills --min 80
Sources
Questions
- Does Cursor support SKILL.md?
- Yes. Cursor's documentation describes Agent Skills as folders with a SKILL.md file, found in project and user skill directories. The agent decides when a skill is relevant from its name and description.
- Where do I put a skill for Cursor?
- In a project, put the folder in .agents/skills/ or .cursor/skills/. For every project, use ~/.agents/skills/ or ~/.cursor/skills/. Cursor also reads the Claude Code and Codex folders for compatibility.
- How do I run a skill in Cursor?
- The agent can pick it up on its own from the description. To run one yourself, type / in Agent chat and search for its name. You can see the list under Customize, then Skills.
- Can I install a skill from GitHub in the Cursor app?
- Per Cursor's docs, skills are not imported one at a time from GitHub. The documented route for a repository is to package skills in a plugin and import it through a marketplace. To use a single skill, copy its folder into a skills directory.
Keep reading
- Skill ScannerScore any skill in your browser. Nothing is uploaded.
- SKILL.md format referenceEvery field, its limit, the folder layout and the errors people hit.
- Codex and Gemini CLI skillsWhere each tool looks for skills, from their docs, and one folder for both.
- How to install Claude Code skillsThree ways to install, the folder paths, and what to do when it does not load.
- All guidesEvery guide, grouped by what you are trying to do.
Paste a SKILL.md or drop a folder. It is scored in your browser and nothing is uploaded.
Want a skill that already passes? Start with a free one.
Taste CoreFreeScan 100/100Spacing, type scale, one accent. From the Frontend Taste collection.