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, suggestionCommit 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 applicableTest 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`: ```yaml --- 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`: ```yaml --- 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`: ```yaml --- 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): ```bash 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.Frequently Asked Questions
What AI tools do developers use most in 2026? Claude Code, GitHub Copilot, and Cursor AI dominate developer workflows. See our Developer Prompts collection.Are AI coding tools worth it? Yes — developers consistently report 20–40% productivity gains on repetitive tasks. Most subscriptions pay for themselves within the first week.
Copilot vs Cursor — which is better? Cursor handles complex multi-file edits better. Copilot integrates into more editors. Most developers who try Cursor prefer it for complex projects.
Is AI-generated code production-ready? AI produces solid starting points, not final code. Always review, test, and refine AI-generated code before deploying to production.
