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

A skill is a version-controlled directory containing a SKILL.md file and optional scripts. SKILL.md has a YAML frontmatter block (name and description) followed by Markdown instructions. They're the same instructions you might type in a long prompt, but stored once and reused automatically.

The split between SKILL.md and scripts/ is the whole point. Put the judgment part in Markdown, where you want the agent to think and use its intelligence. Put the part that must run identically every time in a script. As one field engineer put it: a skill is a combination of a natural-language description to the agent and an explicit deterministic executable script. Reach for a script when you don't want the agent inventing a fresh solution on every run.

You can run a skill yourself from the slash menu, or let Cursor pick it up on its own. The two manual paths are below; either way the agent loads the SKILL.md instructions and follows them.

1. 1Type / in the agent chat panel and search for the skill name (e.g., /write-tests).
2. 2Select the skill to invoke it. The agent loads the SKILL.md instructions and runs the workflow.
3. 3Alternatively, prefix a message with @ and select a skill to attach it as context without running it automatically.

Cursor also discovers skills automatically. When a skill's description matches the current task context, the agent may apply it without an explicit invocation. You still see the agent's reasoning in the trace.

Two ways to make a skill: write the SKILL.md file by hand, or convert an existing rule or slash command with the built-in /migrate-to-skills skill. The steps below cover the manual path, plus the one move that makes it shared rather than personal.

1. 1Add a folder inside .cursor/skills/ (or .agents/skills/) and create a SKILL.md inside it.
2. 2Already have a rule or 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 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. The moment the agent has just done something well (explored a database, produced a report, figured out a build), codify it before the context evaporates.

The strongest pattern field engineers use is explore-once, then codify. Let the agent burn tokens learning your system the slow way the first time. Then turn that hard-won knowledge into a skill so every future run is fast and deterministic.

You don't have to hand-write the file. In chat, or the CLI, run /create skill and Cursor scaffolds it with a built-in template and prompt that captures the workflow you just ran. The flow is interactive: it asks clarifying questions first (where to store it, how deep to go, which parts of the app it covers) before generating. Answer "store this in my project" to make it a project skill the team inherits.

Where you save a skill decides two things: who else gets it, and which files it applies to. Project root (.cursor/skills/) ships the skill with the repo for the whole team; ~/.cursor/skills/ keeps it personal across your projects. A nested folder like src/api/.cursor/skills/ scopes it to files under that subtree. The table below lists every location Cursor scans on startup.

Check .cursor/skills/ into your repository. Every developer who clones the repo gets the same skill library. This is the primary way to enforce coding conventions, runbook steps and team-specific workflows across the agent.

• Coding conventions: write-tests, add-migration, format-pr skills enforce team standards automatically.
• Runbook tasks: deploy-staging, rotate-secrets, check-sentry wrap multi-step ops into one command.
• Domain knowledge: hipaa-review, gdpr-checklist encode compliance checklists the agent runs before shipping.

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

The anti-hallucination value shows up clearly outside code. Without the right context an LLM will go to the wrong place or invent an answer. A skill points it at the source of truth every time.

On startup the agent reads only each skill's name and description, then pulls the full SKILL.md in when the description matches the task. That's progressive disclosureHow skills load: the agent boots knowing only each skill's name and description, then pulls a skill's full instructions into context only at the moment it decides to use it. Press Enter for the full definition.: a one-line summary is cheap, the body loads on demand. If a skill isn't firing when you expect, the description is almost always the culprit. Spell out exactly when it applies.

When in doubt, start with a skill. The write-tests example above is the shape most workflows take: a name, a description that says when it applies, and a few steps the agent follows. Write the SKILL.md, commit it, and reach for 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 clearly isn't the right fit.