How to use SKILL.md files with Cursor

how cursor handles context

Cursor uses .cursorrules, not SKILL.md

Cursor has its own format for persistent instructions. The original format is a .cursorrules file in your project root — plain text that Cursor loads into context at the start of every session. Cursor has since introduced a newer format: .cursor/rules/, a directory where each .mdc file is a rule set that can be scoped to specific file patterns.

SKILL.md files are plain markdown. They're not Cursor-specific, but they work in Cursor because the content is just text instructions — the same instructions Cursor would read from.cursorrules. You copy the skill content into the right place and Cursor reads it.

option 1 — cursorrules

The simple way: paste into .cursorrules

Find a skill on theskills.directory, click Copy, and paste the content into a .cursorrules file in your project root:

.
├── src/
├── package.json
└── .cursorrules       ← paste skill content here

Cursor loads .cursorrules automatically at the start of every session in that project. If the file doesn't exist yet, create it. If it already has content, append the skill below whatever's already there.

To install via the CLI and then move the file:

# Download the skill
npx skillsadd anthropics/skills/frontend-design

# Move SKILL.md content into .cursorrules
cat SKILL.md >> .cursorrules

option 2 — cursor rules directory

The scoped way: .cursor/rules/

If you want different skills to apply to different parts of your project, use Cursor's newer rules directory:

.cursor/
└── rules/
    ├── frontend.mdc      ← applies to src/components/**
    └── database.mdc      ← applies to src/lib/db/**

Each .mdc file can include a frontmatter block that scopes it to specific file patterns. Paste the skill content into the file body — Cursor reads the markdown content directly.

---
description: Frontend design rules
globs: src/components/**/*.tsx
---

# paste SKILL.md content here

This approach works well for monorepos or projects where you want backend and frontend rules kept separate.

multiple skills

Using more than one skill

For .cursorrules, append each skill one after another in the same file. Keep a comment between them so you know what's what:

# --- frontend-design skill ---
[skill content]

# --- vercel-react-best-practices skill ---
[skill content]

For .cursor/rules/, give each skill its own .mdc file. Cursor loads all of them.

If you're starting a new Next.js project and want a full set of rules loaded at once, the Next.js SaaS stack lists the skills that cover frontend, database, and testing — install each one and paste them in sequence.

recommended skills

Skills worth loading into Cursor

These skills encode specific, structural rules — exactly what works best as persistent Cursor context:

• Frontend Design — Anthropic's production design principles. Shapes UI generation decisions — typography, spacing, component weight — so output looks designed rather than default.
• Vercel React Best Practices — 69 rules from Vercel Labs covering RSC boundaries, rendering strategies, image handling, and Suspense. Prevents common App Router mistakes.
• Next.js Best Practices — Routing, error handling, and async component patterns for Next.js App Router projects.
• shadcn/ui — The official shadcn skill from the shadcn-ui org. Covers correct component installation, composition patterns, and theming.
• Systematic Debugging — Four-phase debugging methodology from obra's superpowers collection. Enforces root cause analysis before any fix is written.

committing to version control

Commit your rules with the project

Both .cursorrules and .cursor/rules/ are plain files — commit them to your repo. Every developer who clones the project gets the same Cursor context automatically. No manual setup, no configuration drift.

For teams using both Cursor and Claude Code: you'll want separate files. Claude Code reads SKILL.md and CLAUDE.md. Cursor reads .cursorrules or .cursor/rules/. The content can be identical — copy the same skill text into both.