Creating Skills in Cursor

---

Introduction

Cursor allows developers to extend the capabilities of its AI agent using skills. Not sure what skills are? Start with what are skills in Cursor and how skills work. Skills define reusable workflows that the agent can follow when completing tasks such as running tests, deploying applications, or performing code analysis.

Instead of repeatedly explaining processes to the AI, you can define them once as a skill and reuse them across projects and conversations.

What a Cursor Skill Is

A Cursor skill is a structured markdown file that teaches the agent how to perform a specific workflow. Skills are designed for tasks that involve multiple steps or require consistent execution.

For example, a skill could automate processes like:

• generating unit tests
• deploying a build
• reviewing pull requests
• auditing dependencies
• refactoring code

Each skill contains instructions that the agent reads and follows when the skill is invoked.

Skill Folder Structure

Every skill lives inside a folder that contains a required SKILL.md file.

Example:

.cursor/
└── skills/
    └── run-tests/
        └── SKILL.md

The folder name becomes the skill identifier, which is how the skill is invoked in chat.

More advanced skills can include additional resources such as scripts or templates.

Example extended structure:

run-tests/
├── SKILL.md
├── scripts/
│   └── run-tests.sh
├── references/
│   └── testing-guidelines.md
└── assets/
    └── config-template.json

These optional directories allow skills to include executable code and supporting documentation.

Writing the SKILL.md File

The SKILL.md file contains instructions that guide the agent through the workflow.

A simple example might look like this:

# Run Project Tests

1. Install project dependencies if they are not installed.
2. Run the full test suite.
3. Identify failing tests.
4. Suggest fixes for failing tests.
5. Summarize the test results.

The clearer and more structured the instructions are, the better the agent can follow them.

Adding Metadata

Skills can also include YAML frontmatter at the top of the file. This metadata helps the agent understand when a skill should be used.

Example:

---
name: run-tests
description: Run the full project test suite and analyze failing tests.
---

The description helps the agent determine when the skill is relevant during a conversation.

Where Cursor Looks for Skills

When Cursor starts, it scans specific directories for available skills.

Common locations include:

.agents/skills/
.cursor/skills/
~/.cursor/skills/

These locations allow skills to exist at different levels:

• project-level skills
• repository-specific skills
• global user skills

Cursor also supports compatibility directories used by other AI tools.

.claude/skills/
.codex/skills/
~/.claude/skills/
~/.codex/skills/

Running a Skill

Once a skill exists in a loaded directory, you can invoke it directly in the Cursor chat.

Use a slash command followed by the skill name:

/run-tests

The agent will read the instructions from the skill file and execute the defined workflow.

Using Skills as Context

Sometimes you may want to provide the skill instructions without immediately executing them. In this case, you can attach the skill as context.

Use the @ symbol followed by the skill name:

@run-tests

This allows the agent to reference the instructions while completing another task.

Creating Skills with Cursor

Cursor includes a built-in command that helps generate new skills automatically.

In the agent chat, run:

/create-skill

The agent will guide you through defining the skill name, describing its purpose, and generating the appropriate structure.

This is often the fastest way to create a new skill.

When to Use Skills

Skills are best suited for workflows that involve multiple steps or complex procedures.

Examples include:

• deployment pipelines
• code refactoring processes
• test generation
• dependency audits
• CI/CD validation tasks

Short instructions or coding preferences are usually better handled with rules instead.

Sharing Skills with Teams

Because skills are simple files stored in repositories, they can easily be shared with teammates. Teams can create libraries of common workflows that every developer can use.

Examples of team-wide skills might include:

• deployment procedures
• code review checklists
• internal testing standards
• security scanning workflows

This approach helps ensure consistency across projects.

Conclusion

Skills make Cursor far more powerful by allowing developers to encode workflows directly into the agent’s capabilities. By defining processes as reusable instructions, teams can standardize tasks and reduce repetitive prompts. To see why they're worth adopting, read why we need skills in Cursor; to discover popular options, see best skills in Cursor.

As AI-assisted development continues to evolve, skills provide a practical way to extend agents with domain-specific knowledge and repeatable workflows.