Using zero-skills with Windsurf

February 1, 2026 ยท View on GitHub

This guide explains how to use zero-skills with Windsurf, the AI-powered IDE by Codeium.

Installation

Step 1: Clone zero-skills

cd your-gozero-project/

# Clone to a local directory
git clone https://github.com/zeromicro/zero-skills.git .ai-context/zero-skills

Step 2: Create .windsurfrules

Create .windsurfrules in your project root:

# go-zero Development Rules

You are an expert in go-zero microservices framework development.

## Key Principles

### Architecture
Follow the three-layer architecture strictly:
- **Handler**: HTTP routing only, no business logic
- **Logic**: All business logic, injected via ServiceContext
- **Model**: Data access, generated by goctl

### Code Generation
- Use `goctl` for all boilerplate generation
- API definitions: `.api` files
- RPC definitions: `.proto` files
- Models: `goctl model` command

### Error Handling
```go
// Correct
httpx.Error(w, err)
httpx.OkJson(w, resp)

// Wrong - never do this
fmt.Fprintf(w, "error: %v", err)
w.Write([]byte("error"))

Configuration

  • Load: conf.MustLoad(&c, *configFile)
  • Never hard-code ports, hosts, or credentials
  • Use environment-specific YAML files

Context

  • Always pass ctx context.Context through all layers
  • Use for tracing, cancellation, timeouts

Pattern References

Detailed patterns are in .ai-context/zero-skills/:

  • REST APIs: references/rest-api-patterns.md
  • RPC: references/rpc-patterns.md
  • Database: references/database-patterns.md
  • Resilience: references/resilience-patterns.md

Common Commands

# API generation
goctl api go -api user.api -dir .

# RPC generation
goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.

# Model generation
goctl model mysql datasource -url="user:pass@tcp(localhost:3306)/db" -table="users" -dir="./model"


## Usage

### Cascade AI

Windsurf's Cascade AI works well with go-zero patterns. Use it for:

**Creating services:**

Create a user management REST API with go-zero, including CRUD operations


**Complex refactoring:**

Refactor this handler to follow go-zero three-layer architecture


**Multi-file changes:**

Add JWT authentication middleware to all API routes


### Reference Pattern Files

For detailed patterns, reference the files:

Read .ai-context/zero-skills/references/database-patterns.md and help me add Redis caching


### Chat Interface

Use the chat for go-zero questions:

What's the correct way to handle errors in go-zero handlers?


## Example Workflows

### Creating a New Service

1. **Plan the service:**

Help me plan a user management service with go-zero, including user registration, login, and profile management


2. **Generate API definition:**

Create the user.api file with proper types and routes


3. **Generate code:**
```bash
goctl api go -api user.api -dir .
  1. Implement logic: 
    Help me implement the login logic with password hashing

Adding Database

  1. Create schema:

    Help me create a MySQL schema for the users table

  2. Generate model:

    goctl model mysql datasource -url="..." -table="users" -dir="./model"

  3. Wire up ServiceContext:

    Show me how to add the user model to ServiceContext

Adding Resilience

Read .ai-context/zero-skills/references/resilience-patterns.md and help me add rate limiting to my API

Tips

Use Cascade for Complex Tasks

Cascade excels at multi-file changes. Use it for:

  • Adding new features across multiple files
  • Refactoring to proper architecture
  • Implementing cross-cutting concerns (auth, logging)

Keep Rules Focused

.windsurfrules should be concise. For detailed patterns, reference the pattern files.

Combine with ai-context

For minimal rules:

git clone https://github.com/zeromicro/ai-context.git .ai-context/ai-context

Reference in .windsurfrules:

Follow go-zero workflows from .ai-context/ai-context/
Detailed patterns: .ai-context/zero-skills/references/

Limitations

Compared to Claude Code, Windsurf:

  • No native skills support
  • No YAML frontmatter parsing
  • No subagent workflows
  • No dynamic context injection
  • Manual file references needed

Troubleshooting

Rules Not Applied

Problem: Windsurf ignores go-zero patterns.

Solutions:

  1. Check .windsurfrules in project root
  2. Restart Windsurf
  3. Reference files explicitly

Cascade Timeout

Problem: Complex operations time out.

Solutions:

  1. Break into smaller tasks
  2. Provide more specific instructions
  3. Reference pattern files for context

Generic Suggestions

Problem: Suggestions aren't go-zero specific.

Solutions:

  1. Add more examples to .windsurfrules
  2. Reference pattern files explicitly
  3. Mention "go-zero" in prompts

Additional Resources