Using Skill Seekers with Windsurf IDE

Using Skill Seekers with Windsurf IDE

Last Updated: February 7, 2026 Status: Production Ready Difficulty: Easy ⭐

🎯 The Problem

Windsurf IDE (by Codeium) offers powerful AI flows and Cascade agent, but:

• Generic Knowledge - AI doesn't know your project-specific frameworks or internal patterns
• Manual Context - Copy-pasting documentation into chat is tedious and breaks flow
• Limited Memory - Memory feature requires manual teaching through conversations
• Context Limits - Rules files are limited to 12,000 characters combined

Example:

"When building a FastAPI app in Windsurf, Cascade might suggest outdated patterns or miss framework-specific best practices. You want the AI to reference comprehensive documentation without hitting character limits."

✨ The Solution

Use Skill Seekers to create custom rules for Windsurf's Cascade agent:

1. Generate structured docs from any framework or codebase
2. Package as .windsurfrules - Windsurf's markdown rules format
3. Automatic Context - Cascade references your docs in AI flows
4. Modular Rules - Split large docs into multiple rule files (6K chars each)

Result: Windsurf's Cascade becomes an expert in your frameworks with persistent, automatic context that fits within character limits.

🚀 Quick Start (5 Minutes)

Prerequisites

• Windsurf IDE installed (https://windsurf.com/)
• Python 3.10+ (for Skill Seekers)

Installation

# Install Skill Seekers
pip install skill-seekers

# Verify installation
skill-seekers --version

Generate .windsurfrules

# Example: FastAPI framework
skill-seekers scrape --config configs/fastapi.json

# Package for Windsurf (markdown format)
skill-seekers package output/fastapi --target markdown

# Extract SKILL.md
# output/fastapi-markdown/SKILL.md

Setup in Windsurf

Option 1: Project-Specific Rules (recommended)

# Create rules directory
mkdir -p /path/to/your/project/.windsurf/rules

# Copy as rules.md
cp output/fastapi-markdown/SKILL.md /path/to/your/project/.windsurf/rules/fastapi.md

Option 2: Legacy .windsurfrules (single file)

# Copy to project root (legacy format)
cp output/fastapi-markdown/SKILL.md /path/to/your/project/.windsurfrules

Option 3: Split Large Documentation (for >6K char files)

# Skill Seekers automatically splits large files
skill-seekers package output/react --target markdown --split-rules

# This creates multiple rule files:
# output/react-markdown/rules/
#   ├── core-concepts.md      (5,800 chars)
#   ├── hooks-reference.md    (5,400 chars)
#   ├── components-guide.md   (5,900 chars)
#   └── best-practices.md     (4,200 chars)

# Copy all rules
cp -r output/react-markdown/rules/* /path/to/your/project/.windsurf/rules/

Test in Windsurf

1. Open your project in Windsurf
2. Start Cascade (Cmd+L or Ctrl+L)
3. Test knowledge:

   "Create a FastAPI endpoint with async database queries using best practices"
   

4. Verify Cascade references your documentation

📖 Detailed Setup Guide

Step 1: Choose Your Documentation Source

Option A: Use Preset Configs (24+ frameworks)

# List available presets
ls configs/

# Popular presets:
# - react.json, vue.json, angular.json (Frontend)
# - django.json, fastapi.json, flask.json (Backend)
# - godot.json, unity.json (Game Development)
# - kubernetes.json, docker.json (Infrastructure)

Option B: Custom Documentation

Create myframework-config.json:

{
  "name": "myframework",
  "description": "Custom framework documentation for Windsurf",
  "base_url": "https://docs.myframework.com/",
  "selectors": {
    "main_content": "article",
    "title": "h1",
    "code_blocks": "pre code"
  },
  "categories": {
    "getting_started": ["intro", "quickstart", "installation"],
    "core_concepts": ["concepts", "architecture", "patterns"],
    "api": ["api", "reference", "methods"],
    "guides": ["guide", "tutorial", "how-to"],
    "best_practices": ["best-practices", "tips", "patterns"]
  }
}

Option C: GitHub Repository

# Analyze open-source codebase
skill-seekers github --repo facebook/react

# Or local codebase
skill-seekers analyze --directory /path/to/repo --comprehensive

Step 2: Optimize for Windsurf

Character Limit Awareness

Windsurf has strict limits:

• Per rule file: 6,000 characters max
• Combined global + local: 12,000 characters max

Use split-rules flag:

# Automatically split large documentation
skill-seekers package output/django --target markdown --split-rules

# This creates modular rules:
# - core-concepts.md      (Always On)
# - api-reference.md      (Model Decision)
# - best-practices.md     (Always On)
# - troubleshooting.md    (Manual @mention)

Rule Activation Modes

Configure each rule file's activation mode in frontmatter:

---
name: "FastAPI Core Concepts"
activation: "always-on"
priority: "high"
---

# FastAPI Framework Expert

You are an expert in FastAPI...

Activation modes:

• Always On - Applied to every request (use for core concepts)
• Model Decision - AI decides when to use (use for specialized topics)
• Manual - Only when @mentioned (use for troubleshooting)
• Scheduled - Time-based activation (use for context switching)

Step 3: Configure Windsurf Settings

Enable Rules

1. Open Windsurf Settings (Cmd+, or Ctrl+,)
2. Search for "rules"
3. Enable "Use Custom Rules"
4. Set rules directory: .windsurf/rules

Memory Integration

Combine rules with Windsurf's Memory feature:

# Generate initial rules from docs
skill-seekers package output/fastapi --target markdown

# Windsurf Memory learns from your usage:
# - Coding patterns you use frequently
# - Variable naming conventions
# - Architecture decisions
# - Team-specific practices

# Rules provide documentation, Memory provides personalization

MCP Server Integration

For live documentation access:

# Install Skill Seekers MCP server
pip install skill-seekers[mcp]

# Configure in Windsurf's mcp_config.json
{
  "mcpServers": {
    "skill-seekers": {
      "command": "python",
      "args": ["-m", "skill_seekers.mcp.server_fastmcp", "--transport", "stdio"]
    }
  }
}

Step 4: Test and Refine

Test Cascade Knowledge

# Start Cascade (Cmd+L)
# Ask framework-specific questions:

"Show me FastAPI async database patterns"
"Create a React component with TypeScript best practices"
"Implement Django REST framework viewset with pagination"

Refine Rules

# Add project-specific patterns
cat >> .windsurf/rules/project-conventions.md << 'EOF'
---
name: "Project Conventions"
activation: "always-on"
priority: "highest"
---

# Project-Specific Patterns

## Database Models
- Always use async SQLAlchemy
- Include created_at/updated_at timestamps
- Add __repr__ for debugging

## API Endpoints
- Use dependency injection for database sessions
- Return Pydantic models, not ORM instances
- Include OpenAPI documentation strings
EOF

# Reload Windsurf window (Cmd+Shift+P → "Reload Window")

Monitor Character Usage

# Check rule file sizes
find .windsurf/rules -name "*.md" -exec wc -c {} \;

# Ensure no file exceeds 6,000 characters
# If too large, split further:
skill-seekers package output/react --target markdown --split-rules --max-chars 5000

🎨 Advanced Usage

Multi-Framework Projects

Backend + Frontend Stack

# Generate backend rules (FastAPI)
skill-seekers scrape --config configs/fastapi.json
skill-seekers package output/fastapi --target markdown --split-rules

# Generate frontend rules (React)
skill-seekers scrape --config configs/react.json
skill-seekers package output/react --target markdown --split-rules

# Organize rules directory:
.windsurf/rules/
├── backend/
│   ├── fastapi-core.md          (Always On)
│   ├── fastapi-database.md      (Model Decision)
│   └── fastapi-testing.md       (Manual)
├── frontend/
│   ├── react-hooks.md           (Always On)
│   ├── react-components.md      (Model Decision)
│   └── react-performance.md     (Manual)
└── project/
    └── conventions.md           (Always On, Highest Priority)

Dynamic Context per Workflow

Context Switching Based on Task

---
name: "Testing Context"
activation: "model-decision"
description: "Use when user is writing or debugging tests"
keywords: ["test", "pytest", "unittest", "mock", "fixture"]
---

# Testing Best Practices

When writing tests, follow these patterns...

Scheduled Rules for Time-Based Context

---
name: "Code Review Mode"
activation: "scheduled"
schedule: "0 14 * * 1-5"  # 2 PM on weekdays
priority: "high"
---

# Code Review Checklist

During code review, verify:
- Type annotations are complete
- Tests cover edge cases
- Documentation is updated

Windsurf + RAG Pipeline

Combine Rules with Vector Search

# Use Skill Seekers to create both:
# 1. Windsurf rules (for Cascade context)
# 2. RAG chunks (for deep search)

from skill_seekers.cli.doc_scraper import main as scrape
from skill_seekers.cli.package_skill import main as package
from skill_seekers.cli.adaptors import get_adaptor

# Scrape documentation
scrape(["--config", "configs/react.json"])

# Create Windsurf rules
package(["output/react", "--target", "markdown", "--split-rules"])

# Also create RAG pipeline for deep search
package(["output/react", "--target", "langchain", "--chunk-for-rag"])

# Now you have:
# - .windsurf/rules/*.md (for Cascade)
# - output/react-langchain/ (for custom RAG search)

MCP Tool for Dynamic Context

Create custom MCP tool that queries RAG pipeline:

# mcp_custom_search.py
from skill_seekers.mcp.tools import search_docs

@mcp.tool()
def search_react_docs(query: str) -> str:
    """Search React documentation for specific patterns."""
    # Query your RAG pipeline
    results = vector_store.similarity_search(query, k=5)
    return "\n\n".join([doc.page_content for doc in results])

Register in mcp_config.json:

{
  "mcpServers": {
    "custom-search": {
      "command": "python",
      "args": ["mcp_custom_search.py"]
    }
  }
}

💡 Best Practices

1. Keep Rules Focused

Bad: Single Monolithic Rule (15,000 chars - exceeds limit!)

---
name: "Everything React"
---
# React Framework (Complete Guide)
[... 15,000 characters of documentation ...]

Good: Modular Rules (5,000 chars each)

<!-- react-core.md (5,200 chars) -->
---
name: "React Core Concepts"
activation: "always-on"
---
# React Fundamentals
[... focused on hooks, components, state ...]

<!-- react-performance.md (4,800 chars) -->
---
name: "React Performance"
activation: "model-decision"
description: "Use when optimizing React performance"
---
# Performance Optimization
[... focused on memoization, lazy loading ...]

<!-- react-testing.md (5,100 chars) -->
---
name: "React Testing"
activation: "manual"
---
# Testing React Components
[... focused on testing patterns ...]

2. Use Activation Modes Wisely

3. Prioritize Rules

---
name: "Project Conventions"
activation: "always-on"
priority: "highest"  # This overrides framework defaults
---

# Project-Specific Rules

Always use:
- Async/await for all database operations
- Pydantic V2 (not V1)
- pytest-asyncio for async tests

4. Include Code Examples

Don't just describe patterns:

## Creating Database Models

Use SQLAlchemy with async patterns.

Show actual code:

## Creating Database Models

```python
from sqlalchemy import Column, Integer, String, DateTime
from sqlalchemy.ext.asyncio import AsyncSession
from datetime import datetime

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True)
    email = Column(String, unique=True, nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)

    def __repr__(self):
        return f"<User(email='{self.email}')>"

# Usage in endpoint
async def create_user(email: str, db: AsyncSession):
    user = User(email=email)
    db.add(user)
    await db.commit()
    await db.refresh(user)
    return user

```

Use this pattern in all endpoints.

### 5. Update Rules Regularly

```bash
# Framework updates quarterly
skill-seekers scrape --config configs/react.json
skill-seekers package output/react --target markdown --split-rules

# Check what changed
diff -r .windsurf/rules/react-old/ .windsurf/rules/react-new/

# Merge updates
cp -r .windsurf/rules/react-new/* .windsurf/rules/

# Test with Cascade
# Ask: "What's new in React 19?"

🔥 Real-World Examples

Example 1: FastAPI + PostgreSQL Microservice

Project Structure:

my-api/
├── .windsurf/
│   └── rules/
│       ├── fastapi-core.md       (5,200 chars, Always On)
│       ├── fastapi-database.md   (5,800 chars, Always On)
│       ├── fastapi-testing.md    (4,100 chars, Manual)
│       └── project-conventions.md (3,500 chars, Always On, Highest)
├── app/
│   ├── models.py
│   ├── schemas.py
│   └── routers/
└── tests/

fastapi-core.md

---
name: "FastAPI Core Patterns"
activation: "always-on"
priority: "high"
---

# FastAPI Expert

You are an expert in FastAPI. Use these patterns:

## Endpoint Structure

Always use dependency injection:

\```python
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from app.database import get_db

router = APIRouter(prefix="/api/v1")

@router.post("/users/", response_model=UserResponse)
async def create_user(
    user: UserCreate,
    db: AsyncSession = Depends(get_db)
):
    """Create a new user."""
    # Implementation
\```

## Error Handling

Use HTTPException with proper status codes:

\```python
from fastapi import HTTPException

if not user:
    raise HTTPException(
        status_code=404,
        detail="User not found"
    )
\```

project-conventions.md

---
name: "Project Conventions"
activation: "always-on"
priority: "highest"
---

# Project-Specific Patterns

## Database Sessions

ALWAYS use async sessions with context managers:

\```python
async with get_session() as db:
    result = await db.execute(query)
\```

## Response Models

NEVER return ORM instances directly. Use Pydantic:

\```python
# BAD
return user  # SQLAlchemy model

# GOOD
return UserResponse.model_validate(user)
\```

## Testing

All tests MUST use pytest-asyncio:

\```python
import pytest

@pytest.mark.asyncio
async def test_create_user():
    # Test implementation
\```

Result:

When you ask Cascade:

"Create an endpoint to list all users with pagination"

Cascade will:

1. ✅ Use async/await (from project-conventions.md)
2. ✅ Add dependency injection (from fastapi-core.md)
3. ✅ Return Pydantic models (from project-conventions.md)
4. ✅ Use proper database patterns (from fastapi-database.md)

Example 2: Godot Game Engine

Godot-Specific Rules

# Generate Godot documentation + codebase analysis
skill-seekers github --repo godotengine/godot-demo-projects
skill-seekers package output/godot-demo-projects --target markdown --split-rules

# Create rules structure:
.windsurf/rules/
├── godot-core.md           (GDScript syntax, node system)
├── godot-signals.md        (Signal patterns, EventBus)
├── godot-scenes.md         (Scene tree, node access)
└── project-patterns.md     (Custom patterns from codebase)

godot-signals.md

---
name: "Godot Signal Patterns"
activation: "model-decision"
description: "Use when working with signals and events"
keywords: ["signal", "connect", "emit", "EventBus"]
---

# Godot Signal Patterns

## Signal Declaration

\```gdscript
signal health_changed(new_health: int, max_health: int)
signal item_collected(item_type: String, quantity: int)
\```

## Connection Pattern

\```gdscript
func _ready():
    player.health_changed.connect(_on_health_changed)

func _on_health_changed(new_health: int, max_health: int):
    health_bar.value = (new_health / float(max_health)) * 100
\```

## EventBus Pattern (from codebase analysis)

\```gdscript
# EventBus.gd (autoload singleton)
extends Node

signal game_started
signal game_over(score: int)
signal player_died

# Usage in game scenes:
EventBus.game_started.emit()
EventBus.game_over.emit(final_score)
\```

🐛 Troubleshooting

Issue: Rules Not Loading

Symptoms:

• Cascade doesn't reference documentation
• Rules directory exists but ignored

Solutions:

1. Check rules directory location

   # Must be exactly:
   .windsurf/rules/
   
   # Not:
   .windsurf/rule/  # Missing 's'
   windsurf/rules/  # Missing leading dot
   

2. Verify file extensions

   # Rules must be .md files
   ls .windsurf/rules/
   # Should show: fastapi.md, react.md, etc.
   # NOT: fastapi.txt, rules.json
   

3. Check Windsurf settings

   Cmd+, → Search "rules" → Enable "Use Custom Rules"
   

4. Reload Windsurf

   Cmd+Shift+P → "Reload Window"
   

5. Verify frontmatter syntax

   ---
   name: "Rule Name"
   activation: "always-on"
   ---
   
   # Content starts here
   

Issue: Rules Exceeding Character Limit

Error:

"Rule file exceeds 6,000 character limit"

Solutions:

1. Use split-rules flag

   skill-seekers package output/react --target markdown --split-rules
   

2. Set custom max-chars

   skill-seekers package output/django --target markdown --split-rules --max-chars 5000
   

3. Manual splitting

   # Split SKILL.md by sections
   csplit SKILL.md '/^## /' '{*}'
   
   # Rename files
   mv xx00 core-concepts.md
   mv xx01 api-reference.md
   mv xx02 best-practices.md
   

4. Use activation modes strategically

   <!-- Keep core concepts Always On -->
   ---
   name: "Core Concepts"
   activation: "always-on"
   ---
   
   <!-- Make specialized topics Manual -->
   ---
   name: "Advanced Patterns"
   activation: "manual"
   ---
   

Issue: Cascade Not Using Rules

Symptoms:

• Rules loaded but AI doesn't reference them
• Generic responses despite custom documentation

Solutions:

1. Check activation mode

   # Change from Model Decision to Always On
   ---
   activation: "always-on"  # Not "model-decision"
   ---
   

2. Increase priority

   ---
   priority: "highest"  # Override framework defaults
   ---
   

3. Add explicit instructions

   # FastAPI Expert
   
   You MUST follow these patterns in all FastAPI code:
   - Use async/await
   - Dependency injection for database
   - Pydantic response models
   

4. Test with explicit mention

   In Cascade chat:
   "@fastapi Create an endpoint with async database access"
   

5. Combine with Memory

   Ask Cascade to remember:
   "Remember to always use the patterns from fastapi.md rules file"
   

Issue: Conflicting Rules

Symptoms:

• AI mixes patterns from different frameworks
• Inconsistent code suggestions

Solutions:

1. Use priority levels

   <!-- project-conventions.md -->
   ---
   priority: "highest"
   ---
   
   <!-- framework-defaults.md -->
   ---
   priority: "medium"
   ---
   

2. Make project conventions always-on

   ---
   name: "Project Conventions"
   activation: "always-on"
   priority: "highest"
   ---
   
   These rules OVERRIDE all framework defaults:
   - [List project-specific patterns]
   

3. Use model-decision for conflicting patterns

   <!-- rest-api.md -->
   ---
   activation: "model-decision"
   description: "Use when creating REST APIs (not GraphQL)"
   ---
   
   <!-- graphql-api.md -->
   ---
   activation: "model-decision"
   description: "Use when creating GraphQL APIs (not REST)"
   ---
   

📊 Before vs After Comparison

🤝 Community & Support

• Questions: GitHub Discussions
• Issues: GitHub Issues
• Website: skillseekersweb.com
• Windsurf Docs: docs.windsurf.com
• Windsurf Rules Directory: windsurf.com/editor/directory

📚 Related Guides

• Cursor Integration - Similar IDE, different rules format
• Cline Integration - VS Code extension with MCP
• Continue.dev Integration - IDE-agnostic AI assistant
• LangChain Integration - Build RAG pipelines
• RAG Pipelines Guide - End-to-end RAG setup

📖 Next Steps

1. Try another framework: skill-seekers scrape --config configs/vue.json
2. Combine multiple frameworks: Create modular rules for full-stack projects
3. Integrate with MCP: Add live documentation access via MCP servers
4. Build RAG pipeline: Use --target langchain for deep search
5. Share your rules: Contribute to awesome-windsurfrules

Sources:

• Windsurf Official Site
• Windsurf Documentation
• Windsurf MCP Setup Guide
• Awesome Windsurfrules Repository
• Windsurf Rules Directory
• Mastering .windsurfrules Guide