How to use skills in Cursor

Cursor's agent reads Agent Skills: folders with a SKILL.md file inside .agents/skills/ or .cursor/skills/ in your project, or inside ~/.cursor/skills/ for every project on your machine. Running npx skills add with -a cursor puts a skill in the right place for you. From there, the agent uses the skill when your request fits its description, and you can call it yourself by typing / and its name in chat.

Where Cursor looks for skills

Cursor discovers skills on its own when it starts. Its skills docs list four folders:

Each skill gets its own folder, such as .cursor/skills/schema/SKILL.md. Cursor walks these folders recursively, so category subfolders for grouping are fine. A .cursor/skills/ or .agents/skills/ folder deeper in the repo is picked up too, and its skills only surface when the agent works on files under that directory. That suits a monorepo where one app needs its own skills.

For compatibility, Cursor also loads .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/. So if you already use Claude skills in Claude Code, Cursor sees them without a second install.

If you use Cloud Agents, note that Cursor doesn't copy your user-level skills to them by default. Turning on Sync Skills for Cloud Agents (in Settings, under Agents, then Context and Tools) copies ~/.cursor/skills/ for them. That is the only folder that syncs; ~/.agents/skills/ stays on your machine.

Install a skill with the skills CLI

The skills CLI puts a skill into the folder an agent reads. With -a cursor, it writes to .agents/skills/ in the current project. Add -g and it writes to ~/.cursor/skills/ instead. Cursor reads both. If you leave out -a, the CLI detects which coding agents you have installed and asks you to choose when it finds none.

1. Open a terminal in your project's root folder.

2. To browse the catalog, run the command below. The CLI lists the skills our index serves and asks which ones to install.

   Copy

   npx skills add https://seoskills.sh -a cursor
   

3. To install one skill, copy the command from its page and add -a cursor, or pick Cursor in the page's agent picker, which adds the flag for you. Skills by other authors install from the author's GitHub repository, so the install is credited to them:

   Copy

   npx skills add https://github.com/coreyhaines31/marketingskills --skill schema -a cursor
   

   Our own skills install from our index by slug: npx skills add https://seoskills.sh --skill <slug> -a cursor.

4. To make the skill available in every project, add -g:

   Copy

   npx skills add https://github.com/coreyhaines31/marketingskills --skill schema -g -a cursor
   

5. In Cursor, open Customize in the sidebar and go to Skills to check that the skill is listed.

To see everything the CLI has installed for Cursor, run npx skills ls -a cursor.

Add a skill by hand

A skill is plain files, so the CLI is optional.

1. Create a folder named after the skill: .cursor/skills/schema/ for this project, or ~/.cursor/skills/schema/ for all of them.

2. Copy the skill's whole folder into it, not only SKILL.md. Skills often keep detail in side files. The Schema skill, for example, sends the agent to references/schema-examples.md for full JSON-LD examples, so that file has to come along:

   Copy

   .cursor/skills/schema/SKILL.md
   .cursor/skills/schema/references/schema-examples.md
   

3. Check the frontmatter at the top of SKILL.md. Cursor requires name and description, and name may only use lowercase letters, numbers and hyphens. It must also match the folder name.

4. Open Customize, then Skills, and look for it. Cursor discovers skills at startup, so restart Cursor if it isn't there yet.

To write a new skill instead of copying one, type /create-skill in Agent chat, and Cursor's built-in skill walks you through naming, structuring and saving it. How to write a SKILL.md covers the format.

How Cursor's agent uses a skill

The agent sees the list of discovered skills and decides which ones are relevant to your request, judging from each skill's description. You don't have to name the skill. You can still steer it:

With disable-model-invocation: true, the skill behaves like a slash command: it only loads when you type /skill-name.

SEO skills that suit work in an editor

In Cursor the agent edits your source files, so the skills that pay off are the ones that change templates, metadata and markup. Three to start with:

SEO, by addyosmani

SEO covers technical and on-page SEO, from robots.txt and canonicals to title tags and structured data, and bases its checks on Lighthouse SEO audits and Google Search guidelines. Its description matches requests like "fix meta tags" and "add structured data". It tells the agent to fix the source, re-run the same checks, and not to promise ranking changes.

npx skills add https://github.com/addyosmani/web-quality-skills --skill seo -a cursor

Schema, by coreyhaines31

Schema adds, fixes or optimizes schema.org markup in JSON-LD. Before writing any, it works out the page type, what schema already exists and which rich results you want, and asks about your tech stack. You get a complete JSON-LD block and a testing checklist that starts with the Rich Results Test.

npx skills add https://github.com/coreyhaines31/marketingskills --skill schema -a cursor

SEO AEO Best Practices, by sanity-io

SEO AEO Best Practices is a short SKILL.md that routes the agent to four reference files: a technical SEO checklist (metadata, sitemaps, hreflang, robots.txt), JSON-LD patterns, EEAT, and AI-answer readiness. It tells the agent to start with the one that matches the task. Its own list of when to apply it opens with metadata and Open Graph tags, sitemaps and robots.txt, and JSON-LD.

npx skills add https://github.com/sanity-io/agent-toolkit --skill seo-aeo-best-practices -a cursor

For twelve picks, including skills for Next.js and Nuxt sites, see SEO skills for Cursor, or browse the on-page SEO and technical SEO categories.

When a skill doesn't load or never runs

If the skill isn't listed under Customize, then Skills, check that its folder sits in one of the paths above and holds SKILL.md. Then check the frontmatter: it must be valid YAML, with a name that matches the folder.

If it's listed but the agent never picks it, look for disable-model-invocation: true, or a paths field that leaves out the files you're editing. A skill in a nested .cursor/skills/ folder only appears for files under that directory. Either way, typing / and the skill's name runs it directly.

Next

• Where agents keep skills: the project and global folders for Claude Code, Codex, Gemini CLI and more
• SEO skills for Cursor: curated picks and install steps
• Skill safety: what to check before you install