Windsurf Upgrade & Migration

Current State

Collect the installed editor versions during Step 1; do not execute shell substitutions while loading this skill.

Overview

Guide for upgrading Windsurf to new versions and migrating from VS Code or Cursor. Covers settings transfer, extension compatibility, and Windsurf-specific configuration that doesn't exist in other editors.

Prerequisites

• Current editor installation accessible
• Git for version controlling config files
• Backup of existing settings

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Check Current Windsurf Version

# Current version
windsurf --version

# Check for updates
# Windsurf auto-updates by default
# Manual: Help > Check for Updates (or download from windsurf.com)

Step 2: Migrate from VS Code

Windsurf is VS Code-based and supports most VS Code settings and extensions:

set -euo pipefail
# Windsurf imports VS Code settings on first launch
# For manual migration:

# 1. Export VS Code extensions list
code --list-extensions > vscode-extensions.txt

# 2. Install in Windsurf
cat vscode-extensions.txt | xargs -L1 windsurf --install-extension

# 3. Copy settings
# macOS:
cp ~/Library/Application\ Support/Code/User/settings.json \
   ~/Library/Application\ Support/Windsurf/User/settings.json

# Linux:
cp ~/.config/Code/User/settings.json \
   ~/.config/Windsurf/User/settings.json

Key difference: Remove or disable GitHub Copilot -- it conflicts with Windsurf's Supercomplete.

Step 3: Migrate from Cursor

Cursor and Windsurf both extend VS Code but have different AI config files:

# Mapping Cursor concepts to Windsurf:
cursor_to_windsurf:
  .cursorrules:       .devin/rules/project.md     # AI context rules
  .cursorignore:      .codeiumignore     # AI indexing exclusions
  .cursor/rules/:     .devin/rules/   # Workspace rules
  cursor_settings:    windsurf_settings  # IDE preferences
  Composer:           Cascade            # Agentic AI assistant
  Tab:                Supercomplete      # Inline completions
  Cmd+K:              Cmd+I              # Inline editing
  Cmd+L:              Cmd+L              # AI chat (same!)

Migration script:

#!/bin/bash
set -euo pipefail
echo "Migrating Cursor config to Windsurf..."

# Convert .cursorrules to the preferred Devin Desktop workspace Rule location
mkdir -p .devin/rules
[ -f .cursorrules ] && cp .cursorrules .devin/rules/project.md && echo "Copied .cursorrules → .devin/rules/project.md"

# Convert .cursorignore to .codeiumignore
[ -f .cursorignore ] && cp .cursorignore .codeiumignore && echo "Copied .cursorignore → .codeiumignore"

# Migrate workspace rules
if [ -d .cursor/rules ]; then
  mkdir -p .devin/rules
  cp .cursor/rules/*.md .devin/rules/ 2>/dev/null
  echo "Copied workspace rules to .devin/rules/"
  echo "NOTE: Check frontmatter -- Windsurf uses 'trigger:' field, Cursor uses different format"
fi

echo "Migration complete. Review .devin/rules/project.md for Cursor-specific references."

Step 4: Add Windsurf-Specific Configuration

After migration, add Windsurf-exclusive features:

<!-- New Windsurf features not in VS Code or Cursor -->

1. Cascade Workflows (.windsurf/workflows/*.md)
   - Reusable multi-step automation via slash commands
   - No equivalent in VS Code or Cursor

2. Cascade Memories
   - Persistent facts across sessions
   - Partial equivalent: Cursor notepad

3. Turbo Mode
   - Auto-execute terminal commands
   - Cursor has "auto-run" but different config

4. Browser Previews
   - In-IDE preview with element selection
   - Send UI elements to Cascade for editing

5. Workspace Rules with Trigger Modes
   - glob, always_on, manual, model_decision
   - More granular than Cursor's rule system

Step 5: Post-Upgrade Validation

set -euo pipefail
echo "=== Windsurf Post-Upgrade Check ==="
echo "Version: $(windsurf --version)"
echo "Extensions: $(windsurf --list-extensions | wc -l) installed"
echo "Rules: $([ -f .devin/rules/project.md ] && wc -c < .devin/rules/project.md || echo 'none') bytes"
echo "Ignore: $([ -f .codeiumignore ] && wc -l < .codeiumignore || echo 'none') patterns"

# Test AI features
echo ""
echo "Manual checks:"
echo "1. Open a code file -- Supercomplete should show ghost text"
echo "2. Press Cmd/Ctrl+L -- Cascade should open and respond"
echo "3. Press Cmd/Ctrl+I -- Command mode should activate"

Output

Return a migration record with source and target versions, backed-up settings, extension compatibility, renamed or deprecated behavior, smoke-test evidence, user impact, and rollback steps. Preserve the pre-upgrade profile until verification completes.

Error Handling

Examples

Backup Before Upgrade

# Backup current Windsurf config
tar -czf windsurf-config-backup-$(date +%Y%m%d).tar.gz \
  ~/.config/Windsurf/User/ \
  ~/.codeium/ \
  .devin/rules/project.md \
  .codeiumignore \
  .windsurf/ 2>/dev/null

Check Windsurf Changelog

Visit: https://windsurf.com/changelog
Look for: breaking changes, deprecated settings, new features

Resources

• Focused first-party references
• Windsurf Changelog
• Windsurf Download
• Migrating from Cursor

Related Skill

Continue with windsurf-ci-integration to enforce migrated Rules, ignore patterns, secret controls, and review requirements on every change.