Agent Skills

Agent Skills is an open standard for extending AI agents with specialized capabilities. Skills package domain-specific knowledge and workflows that agents can use to perform specific tasks.

What are skills?

A skill is a portable, version-controlled package that teaches agents how to perform domain-specific tasks. Skills can include scripts, templates, and references that agents may act on using their tools.

How skills work

When Cursor starts, it automatically discovers skills from skill directories and makes them available to Agent. The agent is presented with available skills and decides when they are relevant based on context.

Skills can also be manually invoked by typing / in Agent chat and searching for the skill name.

Built-in Cursor skills

Cursor includes a small set of built in skills to improve your general workflows. These skills are managed by Cursor and appear alongside the skills you add yourself.

You can run any built-in skill by typing / in Agent chat and selecting its name. Agent may also use some built-in skills automatically when your request clearly matches their purpose.

Skill directories

Skills are automatically loaded from these locations:

For compatibility, Cursor also loads skills from Claude and Codex directories: .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/.

Each skill should be a folder containing a SKILL.md file:

.agents/└── skills/    └── my-skill/        └── SKILL.md

Skills can also include optional directories for scripts, references, and assets:

.agents/└── skills/    └── deploy-app/        ├── SKILL.md        ├── scripts/        │   ├── deploy.sh        │   └── validate.py        ├── references/        │   └── REFERENCE.md        └── assets/            └── config-template.json

Nested skill directories

Skill directories can be organized into subdirectories. This is useful for grouping related skills by category, team, or domain. Cursor walks the skills root recursively and picks up any SKILL.md it finds:

.cursor/└── skills/    ├── shipping/    │   ├── land-it/    │   │   └── SKILL.md    │   └── careful-merge-conflicts/    │       └── SKILL.md    ├── debugging/    │   └── using-datadog-mcp/    │       └── SKILL.md    └── workflow/        └── tdd/            └── SKILL.md

The category folder is purely organizational. The skill's identity comes from the folder containing SKILL.md (here land-it, tdd, etc.), not the parent category.

Cursor also discovers skills inside nested project subdirectories. A .cursor/skills/ (or .agents/skills/) folder anywhere inside your repository is picked up, so monorepos can colocate skills with the package they apply to:

my-monorepo/├── .cursor/skills/         # repo-wide skills│   └── land-it/SKILL.md└── apps/    └── web/        └── .cursor/skills/  # app-specific skills            └── deploy-web/SKILL.md

Skills in nested project directories are automatically scoped to files inside that directory. In the example above, deploy-web is only surfaced when the agent works with files under apps/web/, while skills in the repo-wide .cursor/skills/ are available everywhere. This is similar to the paths frontmatter field — you don't need to set paths on a nested skill to scope it to its directory.

SKILL.md file format

Each skill is defined in a SKILL.md file with YAML frontmatter:

---name: my-skilldescription: Short description of what this skill does and when to use it.---# My SkillDetailed instructions for the agent.## When to Use- Use this skill when...- This skill is helpful for...## Instructions- Step-by-step guidance for the agent- Domain-specific conventions- Best practices and patterns- Use the ask questions tool if you need to clarify requirements with the user

Frontmatter fields

Scoping a skill to specific files

Use the paths field to limit a skill to files that match one or more glob patterns. The skill is then only surfaced to the agent when it is reading or editing matching files. This keeps file-specific guidance out of context for unrelated work.

---name: react-component-patternsdescription: Conventions for writing React components in this codebase.paths:  - "**/*.tsx"  - "packages/ui/**/*.ts"---# React component patterns...

You can also pass a single comma-separated string:

---name: python-styledescription: Style rules for Python files.paths: "**/*.py, scripts/**/*.py"---

Patterns follow standard glob syntax. Leave paths unset for a skill that should be available regardless of which files are open.

Disabling automatic invocation

By default, skills are automatically applied when the agent determines they are relevant. Set disable-model-invocation: true to make a skill behave like a traditional slash command, where it is only included in context when you explicitly type /skill-name in chat.

Including scripts in skills

Skills can include a scripts/ directory containing executable code that agents can run. Reference scripts in your SKILL.md using relative paths from the skill root.

---name: deploy-appdescription: Deploy the application to staging or production environments. Use when deploying code or when the user mentions deployment, releases, or environments.---# Deploy AppDeploy the application using the provided scripts.## UsageRun the deployment script: `scripts/deploy.sh <environment>`Where `<environment>` is either `staging` or `production`.## Pre-deployment ValidationBefore deploying, run the validation script: `python scripts/validate.py`

The agent reads these instructions and executes the referenced scripts when the skill is invoked. Scripts can be written in any language—Bash, Python, JavaScript, or any other executable format supported by the agent implementation.

Optional directories

Skills support these optional directories:

Keep your main SKILL.md focused and move detailed reference material to separate files. This keeps context usage efficient since agents load resources progressively—only when needed.

Viewing skills

To view discovered skills, open Customize in the sidebar and go to Skills. Skills installed from plugins or your project appear alongside rules in the Agent Decides section.

Installing skills from GitHub

You can import skills from GitHub repositories:

1. Open Customize in the sidebar
2. Go to Rules and click Add Rule
3. Select Remote Rule (Github)
4. Enter the GitHub repository URL

Migrating rules and commands to skills

Cursor includes a built-in /migrate-to-skills skill in 2.4 that helps you convert existing dynamic rules and slash commands to skills.

The migration skill converts:

• Dynamic rules: Rules that use the "Apply Intelligently" configuration—rules with alwaysApply: false (or undefined) and no globs patterns defined. These are converted to standard skills.
• Slash commands: Both user-level and workspace-level commands are converted to skills with disable-model-invocation: true, preserving their explicit invocation behavior.

To migrate:

1. Type /migrate-to-skills in Agent chat
2. The agent will identify eligible rules and commands and convert them to skills
3. Review the generated skills in .cursor/skills/

Learn more

Agent Skills is an open standard. Learn more at agentskills.io.