skill-seekers-reference/examples/windsurf-fastapi-context/README.md

Windsurf + FastAPI Context Example

Complete example showing how to use Skill Seekers to generate Windsurf rules for FastAPI development.

What This Example Does

• ✅ Generates FastAPI documentation skill
• ✅ Creates modular .windsurfrules for Windsurf IDE
• ✅ Shows Cascade AI-powered FastAPI code generation
• ✅ Handles character limits with split rules

Quick Start

1. Generate FastAPI Skill

# Install Skill Seekers
pip install skill-seekers

# Generate FastAPI documentation skill
skill-seekers scrape --config configs/fastapi.json

# Package for Windsurf with split rules (respects 6K char limit)
skill-seekers package output/fastapi --target markdown --split-rules

2. Copy to Windsurf Project

# Create rules directory
mkdir -p my-fastapi-project/.windsurf/rules

# Copy all rule files
cp -r output/fastapi-markdown/rules/* my-fastapi-project/.windsurf/rules/

# Or use the automation script
python generate_windsurfrules.py --project my-fastapi-project

3. Test in Windsurf

# Open project in Windsurf
windsurf my-fastapi-project/

# Start Cascade (Cmd+L or Ctrl+L)
# Try these prompts:
# - "Create a FastAPI endpoint with async database queries"
# - "Add Pydantic models with validation for user registration"
# - "Implement JWT authentication with dependencies"

Expected Results

Before (Without Rules)

Prompt: "Create a FastAPI user endpoint with database"

Cascade Output:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")
def get_users():
    # Generic sync code
    users = db.query(User).all()
    return users

❌ Uses sync code (not async) ❌ No dependency injection ❌ Returns ORM instances (not Pydantic)

After (With Rules)

Prompt: "Create a FastAPI user endpoint with database"

Cascade Output:

from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from app.database import get_db
from app.schemas import UserResponse

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

@router.get("/users", response_model=list[UserResponse])
async def get_users(
    skip: int = 0,
    limit: int = 100,
    db: AsyncSession = Depends(get_db)
):
    """Get all users with pagination."""
    result = await db.execute(
        select(User).offset(skip).limit(limit)
    )
    users = result.scalars().all()
    return [UserResponse.model_validate(user) for user in users]

✅ Async/await pattern ✅ Dependency injection ✅ Pydantic response models ✅ Proper pagination ✅ OpenAPI documentation

Files in This Example

• generate_windsurfrules.py - Automation script for generating rules
• requirements.txt - Python dependencies
• example-project/ - Minimal FastAPI project structure
  • app/main.py - FastAPI application
  • app/models.py - SQLAlchemy models
  • app/schemas.py - Pydantic schemas
  • app/database.py - Database connection

Rule Files Generated

After running the script, you'll have:

my-fastapi-project/.windsurf/rules/
├── fastapi-core.md           (5,200 chars, Always On)
├── fastapi-database.md       (5,800 chars, Always On)
├── fastapi-authentication.md (4,900 chars, Model Decision)
├── fastapi-testing.md        (4,100 chars, Manual)
└── fastapi-best-practices.md (3,500 chars, Always On)

Rule Activation Modes

File	Activation	When Used
fastapi-core.md	Always On	Every request - core patterns
fastapi-database.md	Always On	Database-related code
fastapi-authentication.md	Model Decision	When Cascade detects auth needs
fastapi-testing.md	Manual	Only when @mentioned for testing
fastapi-best-practices.md	Always On	Code quality, error handling

Customization

Add Project-Specific Patterns

Create project-conventions.md:

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

# Project-Specific Patterns

## Database Sessions

ALWAYS use this pattern:

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

## API Versioning

All endpoints MUST use `/api/v1` prefix:

\```python
router = APIRouter(prefix="/api/v1")
\```

Adjust Character Limits

# Generate smaller rule files (5K chars each)
skill-seekers package output/fastapi --target markdown --split-rules --max-chars 5000

# Generate larger rule files (5.5K chars each)
skill-seekers package output/fastapi --target markdown --split-rules --max-chars 5500

Troubleshooting

Issue: Rules not loading

Solution 1: Verify directory structure

# Must be exactly:
my-project/.windsurf/rules/*.md

# Check:
ls -la my-project/.windsurf/rules/

Solution 2: Reload Windsurf

Cmd+Shift+P → "Reload Window"

Issue: Character limit exceeded

Solution: Re-generate with smaller max-chars

skill-seekers package output/fastapi --target markdown --split-rules --max-chars 4500

Issue: Cascade not using rules

Solution: Check activation mode in frontmatter

---
activation: "always-on"  # Not "model-decision"
priority: "high"
---

Advanced Usage

Combine with MCP Server

# 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"]
    }
  }
}

Now Cascade can query documentation dynamically via MCP tools.

Multi-Framework Project

# Generate backend rules (FastAPI)
skill-seekers package output/fastapi --target markdown --split-rules

# Generate frontend rules (React)
skill-seekers package output/react --target markdown --split-rules

# Organize rules:
.windsurf/rules/
├── backend/
│   ├── fastapi-core.md
│   └── fastapi-database.md
└── frontend/
    ├── react-hooks.md
    └── react-components.md

Related Examples

• Cursor Example - Similar IDE, different format
• Cline Example - VS Code extension with MCP
• Continue.dev Example - IDE-agnostic
• LangChain RAG Example - Build RAG systems

Next Steps

1. Customize rules for your project patterns
2. Add team-specific conventions
3. Integrate with MCP for live documentation
4. Build RAG pipeline with --target langchain
5. Share your rules at Windsurf Rules Directory

Support

• Skill Seekers Issues: GitHub
• Windsurf Docs: docs.windsurf.com
• Integration Guide: WINDSURF.md