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 — the same instructions you might type in a long prompt, but stored once and reused automatically.

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.

1. 1Type /create-skill in agent chat and describe the skill you want. Cursor walks you through naming, structuring and saving it.
2. 2Or create the file manually: add a folder inside .cursor/skills/ (or .agents/skills/) and create a SKILL.md inside it.
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:

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.

A skill is not auto-loaded into context. On startup the agent only reads each skill's name and description, then pulls the full SKILL.md in only when the description matches the task. This is progressive disclosure: a one-line summary is cheap, the body is loaded on demand. The practical consequence - if a skill never fires when you expect it to, the problem is almost always the description, not the instructions. Make the description say plainly when the skill applies.

Plan modeA mode that makes no edits: it researches the codebase and produces an editable plan you review before any code changes. is itself a built-in skill - the same progressive-disclosure mechanism powers the modes you already use, not just the ones you author. A concrete in-the-wild example is the dogfooded de-slop skillA shared Cursor skill that strips typical AI-generated tells (filler comments, vague names, over-engineering) and applies house style.: a skill whose description tells the agent to strip filler and AI-tells from generated prose, so it fires automatically when the agent is about to write copy.