How to Install Cursor Skills

Quick route selector: choose your install method

Installing a Cursor skill means placing a valid SKILL.md into one of the eight scan directories. Select the fastest route for your use case:

---

Method 0: The zero-effort check (Claude Code and Codex)

If you already use Claude Code or Codex and have skills saved in ~/.claude/skills/, .claude/skills/, ~/.codex/skills/, or .codex/skills/, stop here.

Cursor reads all four compatibility directories automatically:

~/.claude/skills/my-skill/SKILL.md  ───► Automatically detected by Cursor

You do not need to move files, create symlinks, or reconfigure Cursor. Open Cursor Agent chat, type /, and verify your skills are already visible.

Note: This compatibility is one-way. Claude Code's official documentation only covers .claude/skills/ and ~/.claude/skills/—it does not read .cursor/skills/ or .agents/skills/. To share a skill between Cursor and Claude Code without duplicating files, store it in .claude/skills/ where Cursor discovers it automatically via its compatibility scanner.

---

Method 1: Create a skill by hand (project or personal)

To install a custom skill, create a folder named after your skill and add a SKILL.md file.

For a project-specific skill (committed to git)

Run this terminal snippet from your repository root:

mkdir -p .cursor/skills/deploy-staging
cat << 'EOF' > .cursor/skills/deploy-staging/SKILL.md
---
name: deploy-staging
description: Deploys the current project branch to the staging environment. Use when asked to deploy or ship to staging.
---

## Deployment Procedure
1. Run `npm test` and verify all tests pass.
2. Build the production bundle: `npm run build`.
3. Deploy to staging cluster and verify health endpoints.
EOF

For a personal skill (available across all projects on your machine)

Run this terminal snippet:

mkdir -p ~/.cursor/skills/my-helper
cat << 'EOF' > ~/.cursor/skills/my-helper/SKILL.md
---
name: my-helper
description: Quick personal helper instructions across all repositories.
---

## Instructions
Instructions for Cursor to follow when invoked.
EOF

[!IMPORTANT] Folder Name Rule: The name field in the frontmatter must match the parent folder name exactly using lowercase letters, numbers, and hyphens. A mismatch will cause Cursor to fail to register the skill.

---

Method 2: Import from GitHub via Cursor UI

Cursor can import skills directly from a remote GitHub repository. Because Cursor integrates skill imports into its configuration surface, the feature is located under the Rules menu:

1. Open Customize in the Cursor sidebar (gear icon).
2. Navigate to Rules and click Add Rule.
3. Select Remote Rule (Github) from the dropdown.
4. Enter the repository URL (e.g., https://github.com/owner/repo).
5. Confirm the import. Cursor will clone the repository's skills into your workspace.

---

Method 3: npx skills (the cross-agent installer)

vercel-labs/skills (MIT, third-party) is an open-source CLI for installing skills from GitHub repositories:

npx skills add <owner/repo> -a cursor

To install the same skill into both Cursor and Claude Code in a single command, chain the -a argument:

npx skills add <owner/repo> -a cursor -a claude-code

The CLI downloads the repository and places the SKILL.md inside your local .cursor/skills/ directory.

---

Method 4: Install from the Cursor Marketplace

When you need an entire workflow suite (multiple skills, subagents, and MCP servers):

1. Open Customize in the Cursor sidebar, or navigate to cursor.com/marketplace.
2. Search for the plugin (e.g., cursor-team-kit, thermos, or pstack).
3. Click Install, and choose whether to apply it to your current Workspace or your global User profile.

All marketplace plugins undergo manual review by Cursor prior to publication.

---

Method 5: Convert existing rules with /migrate-to-skills

If you already have dynamic rules ("Apply Intelligently") or legacy slash commands configured in Cursor, you do not need to rewrite them:

1. Open Cursor Agent chat.
2. Type /migrate-to-skills and press enter.
3. Cursor analyzes your .cursor/rules/ and automatically converts eligible dynamic rules into properly structured SKILL.md files.

For the exact criteria determining which rules convert, see Cursor Skills vs Rules.

---

How to verify installation (step-by-step checklist)

Verify that Cursor has indexed and can execute your newly installed skill:

[ ] Step 1: Open Cursor Agent chat (Cmd+L / Ctrl+L).
[ ] Step 2: Type `/` to bring up the slash command autocomplete menu.
[ ] Step 3: Type your skill's name (e.g. `/deploy-staging`).
            → If the skill appears in the menu, registration succeeded.
[ ] Step 4: Run a trigger test:
            • For manual skills: Select `/skill-name` and hit enter.
            • For automatic skills: Submit a prompt matching your skill's `description`.
            → Verify that the agent references and follows the skill's instructions.

---

Troubleshooting: why Cursor isn't seeing your skill

If your skill fails to appear or trigger, check this diagnostic matrix:

---

Caveats

• We have not run Cursor or executed these installs. Steps are derived directly from Cursor's official documentation and verified against vercel-labs/skills and cursor/plugins.
• npx skills is an independent open-source project by Vercel Labs, not an official Cursor product.
• Cursor documentation does not specify whether a reload is required after creating files on disk; if a newly created skill is not detected immediately, restart Cursor or open a new chat session.

---

Sources

• Cursor — Agent Skills Official Documentation — Directories, Remote Rule import flow, and /migrate-to-skills.
• Cursor — Help Center: Skills — Customization guide and skill directories.
• Cursor — Plugins Official Documentation — Marketplace installation and scopes.
• Claude Code — Skills Documentation — Skill directory locations and cross-agent considerations.
• vercel-labs/skills (GitHub) — npx skills syntax and multi-agent flags.