How to install AI skills in Cursor

Install an AI skill in Cursor by copying the complete skill folder into .cursor/skills/ or .agents/skills/ in your project. For a personal install, use ~/.cursor/skills/ or ~/.agents/skills/. The folder must contain SKILL.md with a lowercase hyphenated name and a useful description. Start Cursor, then invoke /skill-name in Agent chat.

Cursor also recognizes skill directories used by Claude and Codex. This guide sticks to .cursor/skills/ and .agents/skills/, where the path makes project or personal scope explicit. The steps below use a small cursor-release-note-check sample.

Check the folder before you install it

Unzip the download and find the directory that directly contains SKILL.md. Keep the whole directory together. A skill can include scripts, references, templates, and other assets that its instructions expect to find by relative path.

The minimum valid shape is:

cursor-release-note-check/
└── SKILL.md

The open Agent Skills specification requires YAML frontmatter with name and description. The name must use lowercase letters, numbers, and hyphens, stay under 65 characters, and match the parent directory. A minimal entrypoint looks like this:

---
name: cursor-release-note-check
description: Reviews draft release notes for evidence and upgrade steps. Use when preparing a software release note.
---

Read the draft and its linked change evidence before rewriting it.

Read an unfamiliar SKILL.md before copying it into Cursor. Inspect every bundled script, required tool, network call, credential, and write path. Installation gives an agent instructions it may act on with the tools you have allowed.

Choose a project or personal location

Cursor's current Agent Skills documentation lists four primary locations:

| Location | Scope | Use it when | | --- | --- | --- | | .cursor/skills/<name>/SKILL.md | One project | The workflow belongs to this repository. | | .agents/skills/<name>/SKILL.md | One project | You want the open convention inside this repository. | | ~/.cursor/skills/<name>/SKILL.md | All local projects for your user | The workflow is personal and Cursor-specific. | | ~/.agents/skills/<name>/SKILL.md | All local projects for your user | You use the same open-format package across compatible agents. |

Project skills can travel through version control. Personal skills remain on the local machine unless you sync or copy them elsewhere. In a monorepo, Cursor also discovers skills in nested .cursor/skills/ and .agents/skills/ directories. According to Cursor's documentation, a nested skill is scoped to files under that subtree.

Install a project skill

Open a terminal at the project root. From the directory that contains the downloaded sample folder, run:

mkdir -p .cursor/skills
cp -R cursor-release-note-check .cursor/skills/

Confirm that the entrypoint sits directly inside the installed folder:

test -f .cursor/skills/cursor-release-note-check/SKILL.md

Avoid an extra wrapper directory such as .cursor/skills/cursor-release-note-check/cursor-release-note-check/SKILL.md. If a ZIP or repository download adds that level, copy the inner folder that directly contains SKILL.md.

You can use .agents/skills/ instead:

mkdir -p .agents/skills
cp -R cursor-release-note-check .agents/skills/

Commit a project skill only if its license allows team distribution and the folder contains no secrets, customer data, or machine-specific configuration.

Install a personal skill

Copy a workflow you use across local projects into your home directory:

mkdir -p ~/.cursor/skills
cp -R cursor-release-note-check ~/.cursor/skills/

Then verify the exact path:

test -f ~/.cursor/skills/cursor-release-note-check/SKILL.md

Use ~/.agents/skills/ if you prefer the agent-neutral location. Cursor documents both as local user locations, but their remote behavior differs. They aren't interchangeable when Cloud Agents are involved.

Install a skill from GitHub

Cursor documents a UI import path for GitHub repositories. Open Customize, go to Rules, choose Add Rule, select Remote Rule (Github), and enter the repository URL. The current labels are slightly odd for a skill install, so keep the first-party instructions open in case the UI changes.

Read the repository before importing it. The shortcut doesn't tell you whether the license permits your use, what the scripts can do, or whether the folder contains every file referenced by SKILL.md.

Verify that Cursor found the skill

Start Cursor in the project that contains the skill. Open Agent chat, type /, and search for cursor-release-note-check. Select the skill to attach it to one message, then give it a small draft release note and matching evidence.

Test explicit invocation before automatic matching. If /cursor-release-note-check appears and works but a plain request does not select it, the folder is probably installed correctly. The description may not name the job or trigger language clearly enough.

This publisher validated the sample folder and frontmatter locally. It did not run the sample in a live Cursor client, so the discovery and invocation steps above are documentation-derived rather than a claimed runtime result.

Fix a skill that does not appear

Check these in order:

1. The file is named exactly SKILL.md.
2. SKILL.md sits directly inside the skill folder.
3. The name uses lowercase letters, numbers, and hyphens.
4. The name matches the folder that contains SKILL.md.
5. The frontmatter has a non-empty description that explains what the skill does and when to use it.
6. The project skill is inside the repository Cursor has open.
7. No second installed skill uses the same name.

If a newly added skill doesn't appear, restart Cursor and check the slash menu again. Move the folder or rewrite its description only after the exact path and frontmatter pass inspection.

For more detail on discovery and automatic matching, read how AI skills work. If you use OpenAI's coding agent too, its preferred paths and installer differ. Follow the Codex skill installation guide.

Use local skills with Cloud Agents and remote workers

Local personal skills do not automatically follow you into every Cursor environment. Cursor currently documents Sync Skills for Cloud Agents under Settings and says that only ~/.cursor/skills/ is included. The ~/.agents/skills/ directory and unsynced local skills stay on your machine.

Remote SSH sessions and self-hosted workers also do not inherit those local folders. Use project skills committed to the repository or place the skill in the remote worker's image. Treat team publishing as a separate distribution action from personal Cloud Agent sync.

What to inspect before installing a paid skill

A price doesn't change the inspection job. Check the claimed task, included files, license, required tools, network access, expected inputs, output format, and a test you can run on low-risk data. Look for scripts that modify files, call external services, or read credentials.

Capabase lists several kinds of AI setup products, so confirm that the product is actually an Agent Skill folder before following this guide. A bot share link or agent plugin uses a different delivery and installation path.

If you want a packaged workflow, browse AI skills on Capabase. Inspect the full folder and test it in a low-risk project before using it on important work.

Common questions

Does Cursor use .cursor/skills or .agents/skills?

Cursor documents both. Use .cursor/skills/ or .agents/skills/ for project scope, and the same directories under your home folder for local user scope. The package itself still needs a directory containing SKILL.md.

Do I need to restart Cursor after installing a skill?

Cursor says it discovers skills when it starts. Restart after creating a new skill directory if the skill does not appear, then check the slash menu before troubleshooting the description.

Can Cursor install a skill directly from GitHub?

Yes. Cursor's current documentation provides a GitHub import flow under Customize and Rules. Inspect the repository, its license, and its scripts before importing it, and verify the resulting skill in Cursor afterward.