How to Migrate from .cursorrules to Shared Agent Skills

The .cursorrules file served you well, but it has limits

If you've been using Cursor for more than a few months, you probably have a .cursorrules file sitting in your project root. It works. Cursor reads it, the AI follows your conventions, and code reviews get less repetitive.

But as your team grows and your tooling evolves, the cracks start to show:

• The file grows to 500+ lines and becomes hard to maintain
• New teammates don't know the rules exist until they break them
• You started using Claude Code on a second project, and now you're copy-pasting rules between repos
• Someone overwrote the rules file during a merge conflict and nobody noticed for a week
• Your frontend team uses Cursor, your backend team uses Windsurf, and you're maintaining two diverging copies

This guide walks you through migrating your .cursorrules file to versioned, shareable agent skills using localskills.sh. By the end, your rules will be published to a registry, installable with one command, and available to every AI tool your team uses.

Understanding what you're migrating from

Before touching anything, read your existing .cursorrules file carefully. Most files fall into a few categories of content:

Tech stack declarations - "We use TypeScript, Next.js, Tailwind CSS." These are foundational and should apply everywhere.

Coding conventions - Naming patterns, file structure, import ordering. Usually project-specific but often reusable across repositories.

Framework patterns - "Always use App Router, never Pages Router." "Export named functions, not default exports." These are framework-wide and extremely shareable.

Project-specific context - Business domain rules, data model explanations, architectural decisions unique to this codebase. These stay project-local.

Do-not lists - Guardrails against common mistakes. Often reusable once you've established them.

Understanding these categories helps you decide what to share versus what stays in the repository. The goal is to extract everything that applies beyond this one codebase.

If you want a deeper primer on how cursor rules work before migrating, read The Complete Guide to Cursor Rules in 2026.

Step 1: Audit and split your rules file

The biggest migration mistake is treating your .cursorrules file as a single unit. A monolithic rules file is hard to share because not every rule applies to every project or tool.

Start by splitting your file into logical sections. Create a temporary scratch file and sort each rule into one of these buckets:

Universal rules (goes into a shared skill, applies to all projects):

## Code style
- Always use TypeScript with strict mode
- Prefer named exports over default exports
- Use async/await, not .then() chains
- Write descriptive variable names, no single-letter vars outside loops

Framework rules (shared skill per framework, reusable across repos):

## Next.js App Router conventions
- Use the App Router only, no Pages Router
- Route handlers: export async GET/POST/PUT/DELETE functions
- Fetch data in Server Components when possible
- Use `use client` only when you need browser APIs or interactivity

Project-specific rules (stays in the repo as a local .cursorrules or .cursor/rules/ file):

## Our data model
- Users have a tenantId, always filter queries by tenant
- All database writes go through the repository layer, never direct DB calls from routes
- The "billing" module is legacy, don't add new features there

Once you've sorted your rules, you'll likely find that 60-70% of the content is generic enough to share. That's the part worth migrating.

Step 2: Install the localskills CLI

npm install -g @localskills/cli
localskills login

Running localskills login opens a browser window for Google OAuth. After authenticating, the CLI stores a token locally and you're ready to publish.

Step 3: Create your first skill

Create a directory for your skill content. Skills are markdown files, one per focused topic.

mkdir my-typescript-conventions
cd my-typescript-conventions

Create a markdown file with your universal TypeScript rules:

---
description: TypeScript and code style conventions
alwaysApply: true
---

## TypeScript conventions

- Strict mode always enabled
- Prefer `interface` for object shapes, `type` for unions and primitives
- No `any` -- use `unknown` and narrow the type
- All async functions must be typed, no implicit `Promise<any>`

## Naming

- Components: PascalCase
- Functions and variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Files: kebab-case for utilities, PascalCase for components

## Imports

- Group: external packages, then internal aliases, then relative paths
- No barrel files unless the directory is a public API surface

For larger conventions, create multiple files in the same skill package. localskills.sh supports multi-file skills; each file installs as a separate rule in the target tool. See What Are Agent Skills for how multi-file packaging works.

Step 4: Publish to the registry

From inside your skill directory:

localskills publish

The CLI prompts you for:

• Skill name - this becomes the install path, e.g., yourname/typescript-conventions
• Visibility - public (anyone can install), private (only your account), or unlisted (install by URL only)
• Version - starts at 1.0.0, follows semver

After publishing, your skill is live at https://localskills.sh/skills/yourname/typescript-conventions.

For a full walkthrough of the publish flow including team namespaces and API tokens, read Publish Your First Skill in 5 Minutes.

Step 5: Install the skill into your projects

Now replace the content you extracted from .cursorrules with an installed skill. In each project repository:

# Install into Cursor
localskills install yourname/typescript-conventions --target cursor

# Install into multiple tools at once
localskills install yourname/typescript-conventions --target cursor claude windsurf

The CLI writes the skill content into the appropriate location for each tool:

• Cursor: .cursor/rules/yourname-typescript-conventions.mdc
• Claude Code: .claude/skills/yourname-typescript-conventions/SKILL.md
• Windsurf: .windsurf/rules/yourname-typescript-conventions.md

Commit the installed files. Other developers cloning the repo will have the rules immediately. No CLI required to use them, only to update them.

Step 6: Update your .cursorrules file

After installing the shared skill, update your .cursorrules file (or .cursor/rules/ files) to contain only what's truly project-specific:

# Project-specific context

## Data model
- All users belong to a tenant, queries must filter by tenantId
- The `billing` module uses a legacy pattern, don't modify it without a migration plan
- Order statuses: pending, processing, shipped, delivered. No other statuses.

## Architecture decisions
- This service owns only user and order data, never reach into the `inventory` service DB directly
- Background jobs use the `queue` module, not setTimeout or setInterval

The shared skills handle the universal conventions. The local file handles what only your team would know.

Handling team rollout

Publishing a skill is instant, but getting teammates to install it takes coordination. Here's a rollout approach that works:

Week 1: Publish and validate in one repo

Start with your own repository. Publish the skill, install it, and verify that Cursor and Claude Code are following the rules correctly. Check that no important context was lost in the extraction.

Week 2: Pin a version and document the install command

Once you're confident in the skill, pin a specific version in your project's README or onboarding docs:

localskills install yourname/typescript-conventions@1.0.0 --target cursor claude

Pinning versions prevents unexpected changes from breaking teammates' setups. When you release a breaking change to the skill, bump the major version so teams can upgrade deliberately.

Week 3: Roll out to additional repositories

Install the skill in other repos that share the same conventions. The 5-minute install time per repo is the whole point. You're not copying files, you're referencing a versioned artifact.

Ongoing: Update rules in one place

When you need to update a convention, say you've adopted a new testing pattern, update the skill and publish a new version. Teammates run localskills pull to get the latest:

localskills pull

This updates all installed skills in the current repository to their latest compatible versions.

What about rules that only work in Cursor?

Some Cursor rules use Cursor-specific features: the globs field, alwaysApply, or metadata that other tools don't understand. localskills.sh handles this automatically.

When installing to Claude Code or Windsurf, the CLI strips Cursor-specific frontmatter and preserves the rule content. The convention text travels across tools; the tool-specific syntax is generated at install time.

If a rule is truly Cursor-only (e.g., it references Cursor's @codebase symbol or agent behavior), keep it in a Cursor-specific file and don't publish it. The 80% of your rules that are just good instructions work everywhere.

For a deeper look at the format differences across tools, read Using AI Coding Rules Across Tools.

Migration checklist

Here's a quick checklist to verify you've migrated completely:

• Audited existing .cursorrules and split into shared vs. project-specific content
• Created one or more localskills packages for the shared content
• Published packages to localskills.sh with appropriate visibility
• Installed skills in all target repositories and tools
• Updated .cursorrules to contain only project-specific context
• Committed the installed skill files to git
• Documented the install command in the project README or onboarding guide
• Tested that AI tools are following the migrated rules correctly
• Informed teammates of the new workflow and install command

Common issues

"My rules are too project-specific to share."

Start by publishing as unlisted or private. Even if the skill is only useful to your team, you still get versioning, a single source of truth, and one-command installs. You don't have to make rules public to benefit from the registry.

"I have five different .cursorrules files across five repos."

This is exactly the situation localskills.sh is designed for. Pick the most complete file, extract the shared content, publish it, and install it in all five repos. Future changes go in one place.

"My team uses three different AI tools."

Install the skill with multiple --target flags. Each tool gets the content in its native format. One skill, three tools, zero duplication.

"I want to test a rule change before rolling it out."

Publish to a pre-release version, e.g., 1.1.0-beta.1, and install it in a test repository. When you're satisfied, publish the stable version and share the upgrade command with the team.

---

Your .cursorrules file was a good start. Versioned, shareable agent skills are what comes next.

Create your free account and publish your first skill in minutes.

# Install the CLI and publish your first skill
npm install -g @localskills/cli
localskills login
localskills publish