Cursor Agent Skills: How to Use and Create Reusable Agent Commands

A skill is a version-controlled folder with a SKILL.md file and optional scripts. SKILL.md starts with a YAML frontmatter block (name and description), followed by Markdown instructions. Those instructions are what you might otherwise type into a long prompt, stored once and reused.

Use the split between SKILL.md and scripts/ on purpose. Put the judgment in Markdown, where you want the agent to think. Put the part that must run identically every time in a script. As one field engineer put it, a skill combines a natural-language description for the agent with an explicit, deterministic executable script. Use a script when you don't want the agent inventing a fresh solution on every run.

You can run a skill yourself or let the agent pick it up on its own. Either way, the agent loads the SKILL.md instructions and follows them.

1. 1Type / in the agent chat and search for the skill name, for example /write-tests.
2. 2Select the skill to invoke it. The agent loads the SKILL.md instructions and runs the workflow.
3. 3Or type @ and select a skill to attach it to your message as context.

The agent also applies skills without being asked. When a skill's description fits the task, the agent can use it on its own. To keep a skill out of that, set disable-model-invocation: true in its frontmatter, and it runs only when you invoke it by name.

You can write the SKILL.md file by hand, or convert a dynamic rule or a slash command with the built-in /migrate-to-skills skill. Cursor can also draft one for you, as the next section shows. The steps below are the manual path, plus the step that makes a skill shared instead of personal.

1. 1Add a folder inside .cursor/skills/ (or .agents/skills/) and create a SKILL.md inside it.
2. 2Already have a dynamic rule or a slash command that does the job? Convert it with the built-in /migrate-to-skills skill instead of starting from scratch.
3. 3Write YAML frontmatter at the top (a name and a description), then add Markdown instructions below the --- separator.
4. 4Commit the folder to your repo so the whole team shares the skill.

A minimal skill file looks like this:

Right after you finish a task. When the agent has just done something well, such as exploring a database, producing a report or working out a build, write it into a skill before the context is gone.

Presenters in Cursor's workshops follow a habit we call explore once, then codify. Let the agent spend tokens learning your system the slow way the first time. Then turn what it learned into a skill, so later runs start from that knowledge instead of rediscovering it.

You don't have to write the file by hand. Run /create-skill in chat or in the CLI and describe the skill you want. Cursor's help page says this built-in skill walks you through naming, structuring and saving the new skill. In one workshop demo, it asked where to store the skill, which parts of the app it should cover and how deep to go before it generated anything. Answering "store this in my project" made it a project skill the team inherits.

Where you save a skill decides who else gets it and which files it applies to. A skill in the project's .cursor/skills/ ships with the repo for the whole team. One in ~/.cursor/skills/ stays personal and works across your projects on this machine. A nested folder like src/api/.cursor/skills/ scopes the skill to files under that folder.

For compatibility, Cursor also loads skills from the Claude and Codex folders: .claude/skills/ and .codex/skills/, in the project and in your home directory.

Check .cursor/skills/ into your repository, and everyone who clones it gets the same skill library. On Teams and Enterprise plans, you can also publish a personal skill to your team's marketplace, unless an admin has turned member publishing off. Each teammate then chooses whether to install it.

Yes. A skill is a Markdown file, so any team can use one to pin down definitions, canonical sources or a design system the agent must respect.

Outside code, the gain is fewer invented answers. Without the right context, a model can go to the wrong place or make an answer up. A skill points it at the source of truth.

Reach for a rule when the agent should always follow a convention, a skill when only some tasks need a workflow, and a command when you want to start the job yourself. Cursor's docs say the agent uses each skill's description to decide when the skill is relevant, and that skills load their resources on demand. A short description costs little, and the rest arrives when the skill is used. If a skill isn't firing when you expect, rewrite its description to say exactly when it applies.

When in doubt, start with a skill. The write-tests example above shows the usual shape: a name, a description that says when it applies, and a few steps for the agent to follow. Write the SKILL.md, commit it, and switch to a rule or a sub-agentA child agent a main agent spawns to work in parallel with its own context window, handing results back so the parent's context stays clean. Press Enter for the full definition. only when a skill turns out to be the wrong fit.