Windsurf AI-Native Collaborative Development Skill

What This Skill Enables

Claude can guide you through Windsurf's AI-native development environment, featuring Cascade AI for context-aware multi-file operations, Flow collaboration patterns for team coordination, and intelligent code navigation. Windsurf is emerging as a powerful alternative to GitHub Copilot in 2025, with superior multi-file refactoring and real-time collaboration features.

Compatibility

Native

• Claude Code / Claude: native skill usage via SKILL.md.
• Codex/OpenAI workflows: compatible with Agent Skills-style SKILL.md content as reusable workflow instructions.

Manual Adaptation

• Gemini CLI: native skill usage via .gemini/skills/<skill-name>/SKILL.md or .agents/skills/<skill-name>/SKILL.md where supported.
• Cursor: use the generated .cursor/rules/*.mdc adapter for project rules.
• OpenClaw and similar agents: use the same skill content as a reusable prompt/workflow file when native skill import is unavailable.

Prerequisites

Required:

• Windsurf IDE installed (download from codeium.com/windsurf)
• Active project/codebase
• Basic understanding of your tech stack

What Claude helps you master:

• Cascade AI prompts for multi-file operations
• Flow sessions for team collaboration
• Context-aware code navigation
• Intelligent refactoring workflows
• AI-assisted debugging patterns
• Code review with Cascade

How to Use This Skill

Multi-File Refactoring with Cascade

Prompt: "I need to refactor our authentication system from NextAuth to better-auth v1.3.9. Walk me through using Cascade AI to update all files while maintaining existing functionality."

Claude will guide you to:

1. Select all auth-related files in Windsurf sidebar (Cmd/Ctrl+Click)
2. Open Cascade panel (Cmd/Ctrl+K)
3. Use specific Cascade prompt:

   Refactor authentication across these files to use better-auth v1.3.9:
   - Update lib/auth.ts to use betterAuth() instead of NextAuth()
   - Migrate session handling to better-auth patterns
   - Update all import statements
   - Maintain existing OAuth providers
   - Keep current session management logic
   

4. Review Cascade's proposed changes before applying
5. Test authentication flow after refactoring

Flow Collaboration for Feature Development

Prompt: "Show me how to use Windsurf Flow to coordinate with my team on building a real-time notification system."

Claude will explain:

1. Create Flow session (Cmd/Ctrl+Shift+F)
2. Define feature scope with Cascade:

   Implement real-time notifications using Supabase Realtime:
   - Database schema: notifications table with RLS
   - Server-side: Supabase client setup
   - Hooks: useNotifications with real-time subscription
   - UI: NotificationBell component
   - Follow patterns in /lib/supabase and /components/ui
   

3. Cascade generates coordinated changes across multiple files
4. Team members can review and collaborate in Flow session
5. Apply changes with atomic commits

Context-Aware Code Navigation

Prompt: "Help me use Cascade to understand how error handling works across our codebase."

Claude will demonstrate:

1. Select a complex error handling function
2. Right-click → Ask Cascade
3. Use prompt:

   Explain this error handling pattern and show me:
   1. Where else this pattern is used
   2. All files that import this error handler
   3. How errors propagate to the UI layer
   4. Any inconsistencies in error handling
   

4. Cascade provides context-aware analysis with file references
5. Navigate to related code using Cascade's suggestions

Component Extraction with Cascade

Prompt: "Use Cascade to extract a reusable UserProfile component from my dashboard page."

Claude will guide:

1. Select the user profile section in dashboard/page.tsx
2. Open Cascade (Cmd/Ctrl+K)
3. Use extraction prompt:

   Extract user profile section into reusable component:
   - Create components/user/profile.tsx
   - Add TypeScript props interface
   - Support 'compact' and 'full' variants
   - Move styles to component
   - Update dashboard to import and use new component
   

4. Review Cascade's component design
5. Apply changes atomically

Tips for Best Results

1. Specific File Context: When using Cascade, select all related files first (Cmd/Ctrl+Click in sidebar) to provide complete context for multi-file operations.

2. Structured Prompts: Format Cascade prompts with numbered steps or bullet points for complex refactorings to get organized, sequential changes.

3. Reference Existing Patterns: In prompts, reference specific files or patterns ("Follow patterns in /lib/api") to ensure consistency.

4. Atomic Operations: Use Flow sessions for coordinated multi-file changes to maintain codebase integrity.

5. Verify Before Apply: Always review Cascade's proposed changes before applying, especially for critical security or authentication code.

6. Leverage Type Awareness: Windsurf's deep TypeScript integration helps Cascade understand type dependencies across files - mention "maintain type safety" in prompts.

Common Workflows

Complete Feature Implementation

"Use Cascade Flow to implement user profile editing:
1. Database: Add Prisma schema for user profiles
2. API: Create tRPC mutations for profile updates
3. Validation: Define Zod schemas
4. UI: Build profile edit form with react-hook-form
5. State: Add optimistic updates
6. Follow our existing patterns in /lib and /components"

Security Audit with Cascade

"Run Cascade security audit on authentication flow:
1. Analyze all files in /lib/auth and /app/api/auth
2. Check for OWASP Top 10 vulnerabilities
3. Verify input validation with Zod
4. Review session management security
5. Identify any exposed secrets or tokens
6. Suggest security improvements"

Codebase Modernization

"Use Cascade to migrate from React 18 to React 19:
1. Update package.json dependencies
2. Migrate class components to functional components with hooks
3. Replace deprecated lifecycle methods
4. Update ReactDOM.render to createRoot
5. Adopt new React 19 features (useOptimistic, useFormStatus)
6. Update tests for new React Testing Library patterns"

Performance Optimization

"Cascade analysis for performance optimization:
1. Identify components causing unnecessary re-renders
2. Suggest React.memo, useCallback, useMemo placements
3. Find expensive operations that could use useTransition
4. Optimize database queries in Server Components
5. Suggest code splitting opportunities
6. Analyze bundle size impact"

Troubleshooting

Issue: Cascade makes changes that break type safety Solution: In your prompt, explicitly state "maintain strict TypeScript type safety" and "verify all type definitions are updated." Review changes before applying.

Issue: Cascade doesn't understand project-specific patterns Solution: Reference specific files in your prompt: "Follow the API pattern in /lib/api/base.ts" to teach Cascade your conventions.

Issue: Flow sessions become too large and slow Solution: Break large features into smaller Flow sessions focused on specific layers (database, API, UI) rather than entire features at once.

Issue: Cascade refactorings miss edge cases Solution: After Cascade applies changes, ask: "Review the refactoring for edge cases, error handling, and boundary conditions. Suggest tests to verify correctness."

Issue: Team members can't see Flow changes Solution: Ensure Flow session is properly shared (check session permissions) and all team members have latest Windsurf version installed.

Learn More

• Windsurf Documentation
• Cascade AI Guide
• Flow Collaboration Patterns
• Windsurf vs Cursor Comparison
• AI-Native Development Best Practices

Features

• Cascade AI for multi-file context-aware operations with intelligent code understanding across entire codebase
• Flow sessions for team collaboration with real-time shared editing and coordinated multi-file changes
• Intelligent code navigation with AI assistance for understanding complex code relationships and dependencies
• Automated refactoring workflows with atomic multi-file changes and type-safe transformations
• Real-time collaborative coding with team members in shared Flow sessions
• Deep TypeScript and project context understanding for accurate code generation and refactoring
• Context-aware code completion with project-specific patterns and conventions
• AI-assisted debugging patterns with intelligent error analysis and fix suggestions

Use Cases

• Multi-file refactoring and migrations with coordinated changes across entire codebase
• Team-based feature development with Flow sessions for collaborative implementation
• Codebase understanding and navigation with AI-powered code exploration and documentation
• Automated code reviews and quality checks with Cascade AI analysis
• Component extraction and modularization with automatic dependency updates
• Security audits and vulnerability scanning with AI-powered code analysis

• Source repositorygithub.com 2025-10-16
• Documentationdocs.windsurf.com
• Package (SHA-256 pinned)/downloads/skills/windsurf-collaborative-development.zip