Cursor Skills: How to Add Agent Skills and How They Differ from Rules

Cursor skills are folders with a SKILL.md file that the Cursor agent loads when a task needs them, and you add one by placing the folder in .cursor/skills or .agents/skills. Rules still exist next to them, so the practical question is which of the two a given instruction belongs in. This guide answers that first, then shows where Cursor looks, four ways to install a skill, and how to check that it loaded.

Cursor rules vs skills: which one do you need?

Cursor's documentation describes rules and skills separately and does not put them side by side, so the comparison below comes from how each one is documented.

Cursor also supports an AGENTS.md file as a plain-Markdown alternative to structured rules, including nested files in subdirectories where the more specific one takes precedence. If your question is how those instruction files relate, the CLAUDE.md vs AGENTS.md vs skills comparison works through it.

A simple test: if you can state the instruction in a sentence or two and want it applied broadly, write a rule. If it is a procedure, needs a script, or would bloat every conversation, write a skill. Cursor ships a built-in /migrate-to-skills command that converts eligible dynamic rules and slash commands into skills, and a /create-skill skill to start one from scratch.

What are skills in Cursor?

When Cursor starts, it discovers the skills it can see and shows the agent their names and descriptions. The agent decides when one applies. You can also type / in Agent chat, search for the skill and select it, which attaches it to a single message.

Cursor reads a few frontmatter fields beyond the two the standard requires:

• name is required, uses lowercase letters, numbers and hyphens, and must match the parent folder name.
• description is required and says what the skill does and when to use it.
• paths limits the skill to files that match glob patterns.
• disable-model-invocation: true makes the skill run only when you type /skill-name.
• icon and color style the badge when a skill is used as a Custom Mode.
• metadata holds arbitrary key-value pairs.

A skill can also have a scripts/ folder. Cursor's guidance is that scripts should be self-contained, give helpful error messages and handle edge cases. The full format is covered in the SKILL.md format reference.

Where does Cursor look for skills?

Cursor also finds skills folders nested inside your repository. A skill in apps/web/.cursor/skills/ is offered only while the agent works on files under apps/web/, which suits monorepos where each package has its own conventions.

Personal skills in ~/.cursor/skills/ stay on your machine unless you turn on Sync Skills for Cloud Agents. Only that folder is copied. A skill in ~/.agents/skills/ is never synced, so put anything a Cloud Agent needs in the repository.

How do you add a skill to Cursor?

The examples use frontend-design from anthropics/skills, which sits at skills/frontend-design in that repository.

Option 1: import a plugin repository

Cursor's documentation says skills are not imported on their own. To bring skills in from GitHub, they must be packaged as a plugin. In Customize, choose From GitHub Repository and enter the repository. It needs a .cursor-plugin/marketplace.json. After the import, install the plugin and its skills appear in Customize beside your others. You can also add a team marketplace. This route only works for repositories that already ship Cursor plugin metadata, so it is the least common one.

Option 2: the skills CLI

npx skills add anthropics/skills --skill frontend-design -a cursor

This writes into .agents/skills/ in the current project. Add -g for a global install into ~/.cursor/skills/.

Option 3: GitHub CLI

gh skill install anthropics/skills frontend-design --agent cursor
gh skill install anthropics/skills frontend-design --agent cursor --scope user

gh skill is in public preview and needs GitHub CLI 2.90.0 or later. By default it installs at project scope, and --scope user installs for you. The gh skill install manual documents --pin for locking a tag or commit.

Option 4: copy the folder

git clone --depth 1 https://github.com/anthropics/skills.git skills-src
mkdir -p .cursor/skills
cp -r skills-src/skills/frontend-design .cursor/skills/frontend-design
rm -rf skills-src

Copy into ~/.cursor/skills/ for a personal install. Commit .cursor/skills or .agents/skills if you want the team to receive the skill with the repository. The current commands for every agent are on the Cursor page.

How do you check that Cursor loaded a skill?

Open Customize in the sidebar and go to Skills. Discovered skills are listed there, and skills installed from plugins or from your project appear alongside rules in the Agent Decides section. Then type / in Agent chat and search for the skill name.

A skill invoked with / applies to one message. To keep it on for a whole session, use it as a Custom Mode with Option+Enter on a Mac or Alt+Enter on Windows. Either way, the first real test is a prompt that matches the skill's description, followed by a look at whether the agent follows its steps.

Which skills fit Cursor users?

Cursor users spend a lot of time on interface work, so the picks below lean that way. They come from the directory's listings, where each shows its licence and the result of the automated safety check. We have not run each one inside Cursor, so check a skill's own documentation for anything specific to another agent.

• UI/UX Pro Max holds searchable design guidance for web, mobile and desktop interfaces: styles, palettes, font pairings, UX rules and icons. MIT licence.
• Accessibility Fixer audits and fixes HTML accessibility problems such as ARIA labels, keyboard navigation, focus management and contrast, with minimal changes. MIT licence.
• Web Artifacts Builder builds multi-component HTML artifacts as a small React, TypeScript and Tailwind project and bundles it into one file. Apache-2.0 licence.
• Web Application Testing tests local web applications with Python Playwright scripts. Apache-2.0 licence.
• Systematic Debugging requires the agent to find a root cause before it proposes a fix. MIT licence.

Browse the frontend and design category, the accessibility topic or the design systems topic for more. To write your own, the skill authoring topic lists helpers, and Cursor's built-in /create-skill is another starting point.

What if Cursor does not list or trigger a skill?

• The skill is not listed. Confirm the folder contains a file named exactly SKILL.md, and that name matches the folder name.
• It never triggers on its own. The description may be too vague, or disable-model-invocation: true is set, in which case only /skill-name works.
• It seems limited to some files. Look for a paths field in its frontmatter, or check whether it sits in a nested project folder and is scoped to that folder.
• It is missing in a Cloud Agent. Sync copies only ~/.cursor/skills/, never ~/.agents/skills/. Move the skill into the repository.

Update, remove and stay safe

For plugin installs, manage them in Customize, where you installed them. For CLI installs, npx skills update and npx skills remove frontend-design apply, and so does gh skill update. A manual copy is deleted by removing the folder or overwritten by copying a newer version over it.

A skill can tell the agent to run scripts, and the agent acts with the permissions of your Cursor session. Read SKILL.md and anything under scripts/ before installing, particularly for repositories you do not know. Check what a plugin adds before you enable it, and prefer pinning a tag or commit when installing from GitHub.