Cursor Skills: The Practical Guide

What Cursor skills are: the 30-second mental model

Cursor is an AI-powered code editor and agentic development environment. A skill is a directory containing a SKILL.md file: YAML frontmatter defining when the skill applies, followed by step-by-step markdown instructions the agent executes once triggered.

Cursor implemented the open Agent Skills specification in Cursor 2.4 (released 22 January 2026). The core SKILL.md format is shared across agents like Claude Code, Codex, and OpenClaw, though discovery paths, frontmatter extensions, and runtime behavior differ across environments.

Three principles govern how Cursor skills operate:

1. On-demand execution, not standing prompt bloat. Unlike Cursor rules (which inject standing guidance directly into context), skills load only when needed—keeping baseline prompt usage efficient.
2. Three trigger mechanisms. A skill can load automatically via semantic relevance matching, conditionally via file-scoped paths globs, or manually when invoked by name with /.
3. Automatic cross-agent reuse. Cursor scans eight separate directories, including existing Claude Code and Codex locations. If you already have skills installed for Claude Code, Cursor picks them up with zero conversion.

The four Cursor skills tasks

This guide covers the core architecture, trigger mechanics, and directory structure of Cursor skills. For adjacent tasks in this cluster, use the dedicated guides:

How Cursor skills work: the 3 trigger paths

Cursor evaluates and loads skills through three distinct activation paths:

1. Automatic relevance matching

By default, Cursor presents available skill summaries to the model. The model decides when a skill is relevant based on the user's prompt and ongoing session context.

Because the model only sees the name and description during this initial evaluation, the description carries almost the entire discovery burden. A vague description leads to false triggers or complete omission.

2. File-scoped execution (paths)

paths is a Cursor-exclusive addition to the Agent Skills format:

---
name: migration-guard
description: Audits database schema migrations for destructive statements and missing down-migrations.
paths: "db/migrations/**/*.sql, prisma/migrations/**"
---

While other agents only match skills to user prompt phrasing, paths scopes eligibility to the files currently being read or modified. If Cursor touches a file matching the pattern, the skill is surfaced for execution.

3. Explicit invocation and slash commands

Typing / in Cursor Agent chat displays an autocomplete list of all installed skills.

To prevent the agent from triggering a skill automatically without your explicit consent, add disable-model-invocation: true to the frontmatter:

---
name: deploy-staging
description: Triggers a deployment run to the staging cluster.
disable-model-invocation: true
---

This transforms the skill into a deterministic slash command: Cursor will never invoke it autonomously based on chat context, but you can run it deliberately with /deploy-staging.

---

Where Cursor scans for skills: all 8 directories

Cursor looks for skills in eight predefined locations across project and personal scopes. Four are native to Cursor, and four are compatibility paths for Claude Code and Codex:

Per official documentation: "For compatibility, Cursor also loads skills from Claude and Codex directories."

Why this directory list matters

1. Zero-effort cross-agent reuse: If you already maintain skills in ~/.claude/skills/, Cursor loads them automatically with no symlinking, manual copying, or reconfiguration.
2. Cross-agent sharing nuances: Cursor reads compatibility directories for Claude Code (.claude/skills/) and Codex (.codex/skills/), alongside .agents/skills/. However, Claude Code's official documentation only documents reading .claude/skills/ and ~/.claude/skills/—it does not scan .agents/skills/ or .cursor/skills/. To share skills between Cursor and Claude Code without duplicating files, place them in .claude/skills/ so Cursor can discover them via compatibility scanning. For tools that support the Agent Skills standard (Cursor, Codex, OpenClaw), .agents/skills/ is the standard project location.
3. Codex deprecation note: The directory Cursor checks for Codex (~/.codex/skills) was deprecated in Codex in favor of ~/.agents/skills. Because Cursor checks both, skills in either folder will load.

Monorepo and nested subfolder discovery

Skills do not have to live at the workspace root. Cursor discovers .cursor/skills/ and .agents/skills/ folders nested anywhere inside your repository tree.

For example, a skill located at:

packages/billing-service/.cursor/skills/stripe-sync/SKILL.md

is discovered automatically and colocated with the package it governs.

---

The anatomy of a Cursor skill

A minimal skill requires a folder and a SKILL.md file:

.cursor/skills/deploy-staging/
├── SKILL.md         # Required: frontmatter + prompt instructions
├── scripts/         # Optional: bash/node/python utilities the agent can run
├── references/      # Optional: reference docs, API specs, schemas loaded on demand
└── assets/          # Optional: starter templates, icons, boilerplate

Frontmatter specification

name, description, and metadata conform to the Agent Skills open specification. paths and disable-model-invocation are Cursor-specific extensions that are ignored by runtimes adhering strictly to the base standard.

paths vs rule globs

paths on a skill and globs on a rule look similar, but their behavior is fundamentally different:

• A rule's globs injects the rule text directly into the prompt whenever matching files are open or touched.
• A skill's paths makes the skill eligible for consideration, but the body of the skill only loads if the model decides to run the procedure.

For a complete breakdown of when to choose each mechanism, see Cursor Skills vs Rules.

---

Cursor extensibility: skills, rules, commands, plugins, and MCP

Cursor supports five distinct extension mechanisms that are frequently confused:

Understanding the plugin container layer

A Cursor Plugin is not an alternative to a skill—it is a distribution container. A single plugin can bundle multiple skills, rules, subagent definitions, and MCP servers:

my-team-plugin/
├── .cursor-plugin/
│   └── plugin.json       # Manifest metadata
├── skills/
│   └── code-reviewer/
│       └── SKILL.md      # Skill component
├── rules/
│   └── conventions.mdc   # Rule component
└── mcp.json              # MCP tool configuration

Marketplace plugins in the official cursor/plugins repository vary widely in content. Third-party integrations (such as Gmail, Slack, and Salesforce) frequently package only an mcp.json without any skills. In contrast, first-party plugins (like cursor-team-kit and thermos) package multi-skill suites and subagents. For a component-by-component audit of the marketplace, see Cursor Plugins.

---

What you must know before using Cursor skills: 4 critical caveats

Before deploying skills in production workspaces, keep these verified technical boundaries in mind:

1. Context budget is unquantified

Cursor states that skills "load resources on demand, keeping context usage efficient," but publishes no fixed character or token budget.

By comparison, Codex caps its skill catalog index at 2% of the context window or 8,000 characters, and OpenClaw allocates roughly 97 characters per skill plus field lengths. While Cursor gives no exact budget figure, concise and specific descriptions remain critical: every loaded skill consumes context that would otherwise be available for code and conversation history.

2. Duplicate name collisions are undefined

Cursor does not document a formal precedence hierarchy when the same skill name exists in multiple scan directories (e.g., identical skill names in .cursor/skills/ and ~/.claude/skills/).

In contrast, Claude Code documents a strict precedence order and Codex surfaces both without merging. To avoid non-deterministic behavior in Cursor, give custom skills unique names across project and personal scopes.

3. Folder and name alignment is mandatory

The name attribute in SKILL.md frontmatter must match the directory name exactly. If .cursor/skills/audit-tool/SKILL.md specifies name: audit_tool, Cursor will fail to register the skill correctly.

4. No install-time security scanning

Cursor does not statically audit or vet third-party skills at install time. Bundled scripts in a skill's scripts/ directory are executable code. When run via the terminal, command execution is governed by Cursor's Run Modes (Auto-review, Allowlist, or Ask before running) and terminal command sandboxing (via sandbox.json). However, commands can request approvals or run outside the sandbox for full machine access. Always inspect third-party skill files and scripts before adding them to your workspace.

---

Sources

• Cursor — Agent Skills Official Documentation — Directories, frontmatter specifications, nested discovery, and built-in tools.
• Cursor — Run Modes & Security Documentation — Run modes, approvals, permissions, and command sandboxing.
• Cursor — Help Center: Skills — Customization guide and built-in skills overview.
• Claude Code — Skills Documentation — Claude Code skill discovery paths, commands, and configuration.
• Cursor — Rules Official Documentation — Rule storage formats, .mdc schema, and precedence chains.
• Cursor — Plugins Official Documentation — Plugin manifests, packaging, and marketplace installation.
• Cursor 2.4 Release Notes — Official introduction of Agent Skills support in editor and CLI.
• Agent Skills Open Standard — Base specification for SKILL.md.
• Agent Plugins Specification — Specification for distributable agent plugins.