Windsurf Integration Guide

Windsurf AI Integration

Windsurf by Codeium is a powerful AI-native IDE that supports the Agent Skills standard. This guide will help you set up and use skills in Windsurf.

Prerequisites

Windsurf IDE installed
Node.js 18+ with npm/pnpm

Installation Methods

Method 1: CLI Installation

Use the global CLI to install skills:

npx agent-skills install expo/skills/building-native-ui

The skill will be automatically available in your Windsurf workspace.

Method 2: Cascade (Agent Mode)

Windsurf's Cascade feature can directly use skill manifests. In Cascade chat:

Type your request and mention the skill:

Using the expo-native-ui skill, help me build a tab navigation

Cascade will fetch and apply the skill context automatically.

Method 3: Project-Level Configuration

Add skills to your project's .windsurf/skills.json:

{
  "skills": [
    "vercel-labs/agent-skills/vercel-react-best-practices",
    "expo/skills/building-native-ui"
  ]
}

Windsurf will load these skills when you open the project.

Using Skills with Cascade

Windsurf's Cascade (AI Agent) mode is perfect for complex tasks:

@cascade Using the react-best-practices skill, refactor my component to follow Vercel conventions

Cascade will:

Load the skill's knowledge base
Analyze your code
Apply the skill's patterns and suggestions

Popular Skills for Windsurf

Skill	Use Case	Install
Building Native UI	React Native / Expo development	`expo/skills/building-native-ui`
Expo Deployment	App store deployment	`expo/skills/expo-deployment`
Monorepo Best Practices	Managing large codebases	`jaredpalmer/skills/monorepo-best-practices`
Better Auth	Authentication implementation	`better-auth/skills/better-auth-best-practices`

Windsurf vs Cursor: Key Differences

Feature	Windsurf	Cursor
Agent Mode	Cascade (Flow-based)	Composer
Skill Loading	Automatic in Cascade	Manual via settings
Multi-file Edits	Native support	Via Composer
Context Window	Extended (100K+)	Standard

Troubleshooting

Skills Not Loading in Cascade?

Enable Flow Mode: Ensure you're using Cascade in "Flow" or "Agent" mode.
Check Network: Skills are fetched from GitHub; ensure network access.
Restart Windsurf: Sometimes a fresh start helps.

Performance Issues

If skills slow down your workflow:

# Clear the skills cache
npx agent-skills clear-cache

# List installed skills
npx agent-skills list

# Remove unused skills
npx agent-skills remove <skill-name>