Windsurf CLI agent

使用 Windsurf IDE 及其 Cascade AI 代理执行各种软件工程任务的综合技能（更新了 2026 年功能，包括技能、工作流程、内存、MCP 和多代理会话）。

## 概述（中文）

使用 Windsurf IDE 及其 Cascade AI 代理执行各种软件工程任务的综合技能（更新了 2026 年功能，包括技能、工作流程、内存、MCP 和多代理会话）。

## 原文

# Windsurf Cascade Agent Skill

This skill provides a comprehensive guide and set of workflows for utilizing the Windsurf IDE and its Cascade AI agent, including all features from Wave 13 (January 2026).

## Installation

### Download

Download Windsurf Editor from [windsurf.com](https://windsurf.com) for your platform:
- **macOS**: `.dmg` installer (Intel and Apple Silicon)
- **Windows**: `.exe` installer
- **Linux**: `.deb` package (Debian/Ubuntu) or `.tar.gz` tarball

### Post-Installation Setup

**Add to PATH (optional but recommended):**

During onboarding, you can optionally install `windsurf` in PATH to launch from the command line:

```bash
# macOS - create symlink manually if needed
sudo ln -sF /Applications/Windsurf.app/Contents/Resources/app/bin/windsurf /usr/local/bin/windsurf

# Open a project from terminal
windsurf /path/to/project
```

**Import existing configuration:**

Windsurf supports importing settings, extensions, and keybindings from VS Code or Cursor during onboarding. You can also do this later via the Command Palette:

```
Cmd+Shift+P → "Import VS Code Settings"
Cmd+Shift+P → "Import Cursor Settings"
```

### WSL Setup (Windows)

Windsurf supports WSL (Beta). Connect to your WSL instance:
1. Click the bottom-left remote connection button
2. Select "Connect to WSL" or use Command Palette: `Remote-WSL: Connect to WSL`

For CLI access from WSL terminal, create a helper script:

```bash
#!/bin/bash
CURRENT_PATH=$(readlink -f "$1")
windsurf --folder-uri "vscode-remote://wsl+Ubuntu$CURRENT_PATH"
```

### Authentication

Sign up or log in to your Windsurf (formerly Codeium) account during onboarding or via the profile menu.

## Cascade — The AI Agent

Cascade is Windsurf's agentic AI assistant. It understands your entire codebase, tracks your real-time actions (edits, terminal, clipboard), and can autonomously create files, edit code across multiple files, run terminal commands, and maintain project memory.

### Cascade Modes

Cascade comes in two primary modes:

- **Write Mode** (`Cmd+L` / `Ctrl+L`): Full write access — creates files, edits code, runs terminal commands, and makes modifications to your codebase.
- **Chat Mode** (`Cmd+Shift+L` / `Ctrl+Shift+L` to toggle): Read-only — answers questions about your codebase and general coding principles without making changes.

### Model Selection

Switch between models from the dropdown below the Cascade input box. Available models include:

- **SWE-1.5** (Windsurf's own near-frontier model, free for all users)
- **Claude Opus 4.6**, Claude Sonnet 4.5
- **GPT-5.2**, GPT-5.2-Codex, GPT-5.1, GPT-5.1-Codex
- **Gemini 3 Flash**, Gemini 3 Pro
- **Falcon Alpha** (stealth model, speed-optimized)
- **BYOK** (Bring Your Own Key) for custom models

Each prompt consumes credits depending on the model selected.

### Tool Calling

Cascade has a variety of built-in tools:

- **Search**: Semantic code search across your repository
- **Analyze**: Deep analysis of code structure and relationships
- **Web Search**: Search the web for documentation and references
- **MCP**: Call external tools via Model Context Protocol
- **Terminal**: Execute shell commands directly

Cascade can make up to **25 tool calls per prompt**. If the trajectory stops, type `continue` and Cascade will resume.

### Context Selection with @ Mentions

Reference specific files, functions, or context in your prompts:

```
@filename.ts
@src/components/
@function:calculateTotal
```

You can also:
- Drag and drop files from the File Explorer into Cascade
- Send problems from the Problems panel to Cascade
- Highlight errors and click "Explain and Fix"
- @-mention previous conversations for cross-session context

### Voice Input

Use voice input to interact with Cascade via speech-to-text transcription.

### Checkpoints and Reverts

Cascade creates named checkpoints. You can revert changes by hovering over a prompt and clicking the revert arrow, or via the table of contents. **Reverts are currently irreversible.**

## Keyboard Shortcuts

| Action | macOS | Windows/Linux |
|---|---|---|
| Open Cascade (Write) | `Cmd+L` | `Ctrl+L` |
| Toggle Write/Chat | `Cmd+Shift+L` | `Ctrl+Shift+L` |
| Command Palette | `Cmd+Shift+P` | `Ctrl+Shift+P` |
| Inline AI (terminal) | `Cmd+I` | `Ctrl+I` |
| Accept focused diff hunk | `Option+Enter` | `Alt+Enter` |
| Reject focused diff hunk | `Option+Shift+Backspace` | `Alt+Shift+Backspace` |
| Fast Context (first msg) | `Cmd+Enter` | `Ctrl+Enter` |

## Skills

Skills let you bundle instructions, templates, checklists, and supporting files into folders that Cascade can invoke for complex, multi-step tasks.

### Creating a Skill

1. Click the Customizations icon in Cascade's top-right slider menu
2. Navigate to the Skills panel
3. Click `+ Workspace` (project-specific) or `+ Global`
4. Name the skill (lowercase letters, numbers, hyphens only)

### Skill Structure

Each skill is a folder with a `SKILL.md` file and optional supporting files:

```
.windsurf/skills/deploy-to-production/
├── SKILL.md
├── deployment-checklist.md
├── rollback-procedure.md
└── config-template.yaml
```

### SKILL.md Format

```markdown
---
name: deploy-to-production
description: Guides the deployment process to production with safety checks
---

## Pre-deployment Checklist
1. Run all tests
2. Check for pending migrations
3. Verify environment variables
...
```

The `name` field is used for display and @-mentions. The `description` helps Cascade decide when to automatically invoke the skill.

### Invoking Skills

- **Automatic**: Cascade uses progressive disclosure to invoke skills when they're relevant to your task
- **Manual**: @-mention the skill name in your prompt

For the full Skills specification, visit [agentskills.io](https://agentskills.io).

## Workflows

Workflows define a series of steps to guide Cascade through repetitive tasks. They are saved as markdown files and invoked via slash commands.

### Creating a Workflow

1. Click Customizations icon → Workflows panel → `+ Workflow`
2. Or ask Cascade to generate a Workflow for you

### Workflow Storage

Workflows are saved in `.windsurf/workflows/` directories. Windsurf discovers them from:
- Current workspace and sub-directories
- Parent directories up to the git root (for git repos)
- Multiple workspace support with deduplication

Workflow files are limited to **12,000 characters** each.

### Invoking Workflows

```
/workflow-name
```

Workflows can call other workflows:

```markdown
## Steps
1. Call /lint-and-format
2. Call /run-tests
3. Deploy to staging
```

### Example Workflow — PR Review

```markdown
---
name: pr-review
description: Review PR comments and address them
---

## Steps
1. Check out the PR branch: `gh pr checkout [id]`
2. Get comments on PR:
   ```bash
   gh api --paginate repos/[owner]/[repo]/pulls/[id]/comments | jq '.[] | {user: .user.login, body, path, line}'
   ```
3. For EACH comment, address the feedback and commit the fix
4. Push changes and reply to each comment
```

## Memories & Rules

Memories persist context across Cascade conversations. Rules guide Cascade behavior.

### Memories

- **Auto-generated**: Cascade creates memories when it encounters useful context. Does NOT consume credits.
- **User-created**: Type `create memory ...` in Cascade to manually save context.
- Auto-generated memories are workspace-specific.

**Managing Memories:**
- Windsurf Settings → Settings tab → Manage next to "Cascade-Generated Memories"
- Or: three dots in Cascade → Manage Memories
- Toggle auto-generation: Settings → "Auto-Generate Memories"

### Rules

Rules are manually defined instructions for Cascade.

**Rule Levels:**
- `global_rules.md` — applies across all workspaces
- `.windsurf/rules/` — workspace-level directory with rules tied to globs or descriptions
- System-level rules (Enterprise) — deployed via MDM policies

**Activation Modes:**
- **Always*