How to Migrate .cursorrules to SKILL.md (Step-by-Step, 2026)

How to Migrate .cursorrules to SKILL.md (Step-by-Step, 2026)

If you've built up a .cursorrules file in Cursor and want your instructions to work across Claude Code, Codex CLI, Gemini CLI, and every other agent that supports the open standard, you need to convert them to SKILL.md. Here's exactly how to do it, with before-and-after examples.

Quick Answer: Split your .cursorrules file into two parts. Project-wide context (stack, conventions, style preferences) stays in .cursorrules or moves to CLAUDE.md. Task-specific workflows (code review steps, commit message formats, test generation procedures) become individual SKILL.md files in separate folders. Each skill gets YAML frontmatter with name, description, and optionally when_to_use, plus markdown instructions below. Place skills in .cursor/skills/ for Cursor, ~/.claude/skills/ for Claude Code, or the equivalent directory for other agents. The same skill file works everywhere without modification.

Why migrate

A .cursorrules file locks your instructions into Cursor. If you switch to Claude Code, try Codex CLI, or work with a teammate who uses a different agent, your customizations don't transfer.

SKILL.md is an open standard adopted by Claude Code, Codex CLI, Gemini CLI, GitHub Copilot (agent mode), Cursor, and others. A skill written once works across all of them. You write your code review process as a SKILL.md, and it works whether you're in a terminal with Claude Code or in Cursor's IDE.

The other reason: .cursorrules loads everything into every conversation. If your file is 400 lines covering code review, commit messages, test generation, and deployment, all of that context gets consumed on every interaction, even when you're just asking Cursor to rename a variable. SKILL.md skills load on demand. Only the relevant skill gets loaded when the agent detects a matching request.

For a detailed comparison of the formats, see SKILL.md vs .cursorrules vs AGENTS.md.

Step 1. Audit your .cursorrules

Open your .cursorrules file and categorize every block of instructions into one of two buckets:

Always-on context. Things the agent should know for every interaction in this project: your tech stack, language version, framework choices, coding style preferences, naming conventions, directory structure. This is project identity.

Task-specific workflows. Step-by-step procedures for specific jobs: how to review code, how to write commit messages, how to generate tests, how to handle deployments. These have a trigger ("when the user asks to review code, do X").

Here's a typical .cursorrules file with both types mixed together:

# Project: My SaaS App
# Stack: Next.js 14, TypeScript, Tailwind, Supabase
# Always use named exports
# Prefer server components unless client interactivity is needed
# Use kebab-case for file names
# All API routes go in app/api/

# Code Review Process
When reviewing code:
1. Check for TypeScript errors first
2. Look for missing error handling in async functions
3. Verify Supabase RLS policies are referenced for data access
4. Check that new components follow the existing naming pattern
5. Flag any direct DOM manipulation in React components
6. Output a summary table: file, issue, severity, suggestion

# Commit Messages
When writing commit messages:
1. Use conventional commit format: type(scope): description
2. Types: feat, fix, refactor, docs, test, chore
3. Keep the subject line under 72 characters
4. Add a body if the change is non-obvious
5. Reference issue numbers when applicable

# Test Generation
When generating tests:
1. Use Vitest, not Jest
2. Follow the existing pattern in __tests__/
3. Mock Supabase client using the existing mock in test/mocks/
4. Cover the happy path plus at least one error case
5. Use descriptive test names: "should [action] when [condition]"

In this file, the first 6 lines are always-on context. The three blocks below are task-specific workflows that should become skills.

Step 2. Keep project context where it belongs

The always-on context stays in a project-level file. You have two options:

Option A: Keep it in .cursorrules if you primarily use Cursor. The file continues to work as before for project-wide context.

Option B: Move it to CLAUDE.md if you use Claude Code (or both). CLAUDE.md serves the same purpose as .cursorrules: always-on project context loaded at session start. The format is plain markdown.

For more on the difference, read SKILL.md vs CLAUDE.md.

Either way, remove the task-specific workflow sections from this file. They're about to become skills.

Step 3. Convert each workflow to a SKILL.md

Each task-specific workflow becomes its own skill in its own folder. Here's how to convert the code review block from the example above.

Before (.cursorrules)

# Code Review Process
When reviewing code:
1. Check for TypeScript errors first
2. Look for missing error handling in async functions
3. Verify Supabase RLS policies are referenced for data access
4. Check that new components follow the existing naming pattern
5. Flag any direct DOM manipulation in React components
6. Output a summary table: file, issue, severity, suggestion

After (SKILL.md)

Create the folder .cursor/skills/code-reviewer/ and add a file called SKILL.md:

---
name: code-reviewer
description: Reviews code changes for TypeScript errors, missing error handling, Supabase RLS compliance, naming conventions, and React anti-patterns. Use when the user asks to review code, check changes, or says "review this."
---

## Steps

1. Check for TypeScript type errors and missing type annotations.
2. Look for missing error handling in async functions. Every await should be in a try/catch or have a .catch() handler.
3. Verify that any data access references the appropriate Supabase RLS policy. Flag queries that bypass RLS.
4. Check that new components follow the existing naming pattern in the project.
5. Flag any direct DOM manipulation in React components. Suggest React refs or state instead.
6. Output a summary table with columns: File, Issue, Severity (high/medium/low), Suggestion.

## Output format

| File | Issue | Severity | Suggestion |
|---|---|---|---|
| src/components/UserCard.tsx | Missing error boundary | medium | Wrap async data fetch in try/catch |

If no issues are found, say so explicitly. Don't invent problems.

The key differences from .cursorrules:

YAML frontmatter at the top between --- markers. The name field must match the folder name. The description field is what the agent reads to decide when to load this skill. Make it specific.

Standalone instructions. The skill doesn't assume any project context because it loads independently. If the skill needs project-specific info (like "we use Supabase"), the agent gets that from .cursorrules or CLAUDE.md at runtime. The skill provides the workflow; the project file provides the context.

On-demand loading. This skill only loads when the user asks for a code review. It doesn't consume tokens during unrelated tasks.

Converting the commit message workflow

Create .cursor/skills/commit-writer/SKILL.md:

---
name: commit-writer
description: Writes conventional commit messages from staged git changes. Use when the user asks to write a commit message, commit changes, or says "commit this."
---

## Steps

1. Read the staged diff using git diff --cached.
2. Identify what changed: new features, bug fixes, refactors, documentation, tests, or chores.
3. Write a commit message in conventional format: type(scope): description
4. Allowed types: feat, fix, refactor, docs, test, chore.
5. Keep the subject line under 72 characters.
6. Add a body paragraph if the change is non-obvious or touches multiple files.
7. Reference issue numbers if mentioned in the conversation or visible in branch names.

## Examples

feat(auth): add password reset flow via Supabase

fix(api): handle null response from external pricing endpoint

refactor(components): extract UserAvatar into shared component

Converting the test generation workflow

Create .cursor/skills/test-generator/SKILL.md:

---
name: test-generator
description: Generates test files using Vitest that match existing project test conventions. Use when the user asks to write tests, add test coverage, or create a test file.
---

## Steps

1. Detect the existing test structure by checking __tests__/ directories and existing test files.
2. Use Vitest. Do not use Jest.
3. Import the Supabase mock from test/mocks/ if the code under test accesses Supabase.
4. Write at least two test cases: the happy path and one error case.
5. Use descriptive test names in the format: "should [action] when [condition]."
6. Follow the naming pattern of existing tests (e.g., ComponentName.test.tsx).
7. Place the test file alongside existing tests in __tests__/ or co-located with the source file, matching whichever convention the project already uses.

Step 4. Place skills in the right directory

For Cursor, skills go in .cursor/skills/ at your project root:

your-project/
├── .cursor/
│   └── skills/
│       ├── code-reviewer/
│       │   └── SKILL.md
│       ├── commit-writer/
│       │   └── SKILL.md
│       └── test-generator/
│           └── SKILL.md
├── .cursorrules          # still has your always-on context
├── src/
└── package.json

Reload Cursor (Cmd/Ctrl+Shift+P, "Developer: Reload Window") to pick up the new skills.

For Claude Code, the same skill folders go in ~/.claude/skills/ (personal) or .claude/skills/ (project-scoped):

cp -r .cursor/skills/* ~/.claude/skills/

For Codex CLI, copy to ~/.codex/skills/. For Gemini CLI, copy to ~/.gemini/skills/. The SKILL.md files work in all of them without modification.

For details on each agent's paths, see Where Are Claude Skills Stored? and the equivalent guides for Codex CLI, Gemini CLI, and Cursor.

Step 5. Test the migration

After placing the skills, verify they work:

1. Start a new session in your agent of choice.
2. Ask it to do something that should trigger each skill: "review this code," "write a commit message," "generate tests for UserCard."
3. Confirm the agent follows the skill's instructions instead of defaulting to generic behavior.

If a skill doesn't trigger, check that the description field is specific enough. "Helps with code" is too vague. "Reviews code changes for TypeScript errors, error handling, and Supabase compliance" gives the agent clear matching criteria.

To verify your skills more rigorously, use the skill-creator's eval mode to run structured tests.

What to keep in .cursorrules

After migration, your .cursorrules should be lean. It should contain only project identity and conventions:

# Stack: Next.js 14, TypeScript, Tailwind, Supabase
# Use named exports
# Prefer server components unless client interactivity is needed
# kebab-case for file names
# API routes in app/api/
# Database: Supabase with RLS enabled

Everything else lives in skills that load on demand.