How to Migrate from .cursorrules to Agent Skills

What is .cursorrules?

If you use Cursor, you've probably created a .cursorrules file. It's a single file in your project root that contains instructions for Cursor's AI assistant. You might tell it about your tech stack, coding conventions, preferred patterns, or things to avoid.

A typical .cursorrules file looks something like this:

You are an expert in TypeScript, React, and Next.js.

Always use functional components with hooks.
Use Tailwind CSS for styling, never inline styles.
Write tests with Vitest and React Testing Library.
Follow the existing project structure in src/components/.
Never use default exports.
Use named exports for everything.
When writing API routes, always validate input with Zod.
Handle errors with try/catch and return proper HTTP status codes.

This works fine inside Cursor. But the moment you switch to Claude Code, Windsurf, GitHub Copilot, or any other AI tool, those instructions don't follow you. They're locked to one tool and one project.

What are Agent Skills?

Agent Skills are portable agent definitions that work across 40+ AI tools. Each skill is a Markdown file with YAML frontmatter that defines the agent's identity, and a Markdown body that contains its instructions.

The key differences from .cursorrules:

• Portable. Agent skills work in Claude Code, Cursor, Windsurf, GitHub Copilot, and dozens of other tools that follow the Agent Skills spec.
• Versioned. Each agent has a semantic version number, so you know when its behavior changes.
• Shareable. You can publish agents to registries like Agent Shelf, and other developers can download and use them.
• Focused. Instead of one file with all your rules, each agent handles one responsibility.

Why migrate?

If your .cursorrules file works and you only use Cursor, you might not need to migrate. But here's when it makes sense:

Your team uses different AI tools. One developer uses Cursor, another uses Claude Code, a third uses Windsurf. Agent skills give everyone the same instructions regardless of their tool.

Your rules are getting long. A 500-line .cursorrules file is hard to maintain. Splitting it into focused agents makes each one easier to read, test, and update.

You want to share with other projects. Your React component patterns aren't specific to one repo. As agent skills, you can reuse them across projects or share them with the community.

You want versioning. When you change a coding standard, you want to track that change. Agent skills have built-in version numbers.

Step-by-step migration

Step 1: Read your .cursorrules file

Start by reading through your entire .cursorrules file. Highlight or group the instructions by topic. Most files contain a mix of:

• General persona instructions ("You are an expert in...")
• Technology-specific rules ("Use TypeScript strict mode")
• Project-specific conventions ("Components go in src/components/")
• Code style rules ("Use named exports")
• Workflow instructions ("Always write tests before implementation")

Step 2: Split into separate concerns

Each group of related instructions becomes its own agent. The goal is one agent per job. Using the example above, you might split into:

• React component agent - Component patterns, hooks usage, styling rules
• API route agent - Input validation, error handling, response formats
• Testing agent - Test framework, patterns, coverage requirements

A good test: can you describe what each agent does in one sentence without using "and"? If not, split further.

Step 3: Add YAML frontmatter to each

Every agent needs frontmatter that identifies it. Here's how to convert the React rules from our example:

Before (.cursorrules, mixed in with everything else):

Always use functional components with hooks.
Use Tailwind CSS for styling, never inline styles.
Never use default exports.
Use named exports for everything.

After (standalone agent file):

---
id: react-component-patterns
name: React Component Patterns
description: Enforces functional component patterns with Tailwind CSS and named exports
version: 1.0.0
category: coding
tags:
  - react
  - tailwind
  - components
---

You are a React specialist who enforces consistent component patterns.

## Component Rules

- Always use functional components with hooks. Never use class components.
- Use Tailwind CSS utility classes for all styling. Never use inline styles or CSS modules.
- Use named exports for all components. Never use default exports.

## File Structure

- One component per file
- Name the file the same as the component (e.g., `UserProfile.tsx`)
- Place components in `src/components/` organized by feature

## Example

Good:
\`\`\`tsx
export function UserProfile({ name, email }: UserProfileProps) {
  return (
    <div className="flex flex-col gap-2 p-4">
      <h2 className="text-lg font-semibold">{name}</h2>
      <p className="text-sm text-gray-600">{email}</p>
    </div>
  );
}
\`\`\`

Notice how the agent file is more detailed than the original rules. That's the point. Each agent has room to include examples and explain the reasoning behind each rule.

Step 4: Place in your project directory

Agent skills live in the .agents/agents/ directory at your project root:

your-project/
├── .agents/
│   └── agents/
│       ├── react-component-patterns.md
│       ├── api-route-standards.md
│       └── testing-conventions.md
├── src/
├── package.json
└── .cursorrules  (you can keep this for now)

AI tools that support the Agent Skills spec will automatically discover agents in this directory.

Step 5: Optionally publish to Agent Shelf

If your agents aren't project-specific, consider publishing them to Agent Shelf. Other developers working with the same tech stack can discover and use them.

You can publish directly from your terminal using the Agent Shelf skill:

Use the agentshelf skill to publish my agents

Or use the web interface at agentshelf.io/upload.

What stays in .cursorrules?

Not everything should move to agent skills. Keep these in .cursorrules (or your tool's equivalent project config):

• Project-specific paths and structure that only apply to this repo
• Environment details like "this project uses pnpm, not npm"
• Team preferences that are too specific to share ("ask @sarah for database schema questions")

Move these to agent skills:

• Language and framework patterns (React, Python, Go conventions)
• Code review criteria (what to check, how to report findings)
• Testing patterns (framework setup, coverage rules, test structure)
• Any instructions you'd want in another project

The split is simple: if it's reusable, it's an agent skill. If it's specific to this one repo, it stays in project config.

After migrating

Once your agents are in place, you can delete the corresponding sections from .cursorrules to avoid conflicting instructions. Some teams keep a minimal .cursorrules that just references their agents:

This project uses agent skills in .agents/agents/ for coding standards.
Refer to those agents for React, API, and testing conventions.

You can also install agents from the community. Browse the Agent Shelf registry to find agents for your stack, or check the getting started guide for a walkthrough of discovering and downloading agents.

The documentation covers the full agent definition format, including optional fields like license and tags that help others find your agents when you publish them.