{"skill":{"slug":"windsurf-cascade","displayName":"Windsurf CLI agent","summary":"A comprehensive skill for using the Windsurf IDE and its Cascade AI agent for various software engineering tasks (updated for 2026 features, includes Skills,...","description":"---\nname: windsurf-cascade\nversion: 1.0.0\ndescription: A comprehensive skill for using the Windsurf IDE and its Cascade AI agent for various software engineering tasks (updated for 2026 features, includes Skills, Workflows, Memories, MCP, and multi-agent sessions).\nauthor: Lucas Carrijo\n---\n\n# Windsurf Cascade Agent Skill\n\nThis 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).\n\n## Installation\n\n### Download\n\nDownload Windsurf Editor from [windsurf.com](https://windsurf.com) for your platform:\n- **macOS**: `.dmg` installer (Intel and Apple Silicon)\n- **Windows**: `.exe` installer\n- **Linux**: `.deb` package (Debian/Ubuntu) or `.tar.gz` tarball\n\n### Post-Installation Setup\n\n**Add to PATH (optional but recommended):**\n\nDuring onboarding, you can optionally install `windsurf` in PATH to launch from the command line:\n\n```bash\n# macOS - create symlink manually if needed\nsudo ln -sF /Applications/Windsurf.app/Contents/Resources/app/bin/windsurf /usr/local/bin/windsurf\n\n# Open a project from terminal\nwindsurf /path/to/project\n```\n\n**Import existing configuration:**\n\nWindsurf supports importing settings, extensions, and keybindings from VS Code or Cursor during onboarding. You can also do this later via the Command Palette:\n\n```\nCmd+Shift+P → \"Import VS Code Settings\"\nCmd+Shift+P → \"Import Cursor Settings\"\n```\n\n### WSL Setup (Windows)\n\nWindsurf supports WSL (Beta). Connect to your WSL instance:\n1. Click the bottom-left remote connection button\n2. Select \"Connect to WSL\" or use Command Palette: `Remote-WSL: Connect to WSL`\n\nFor CLI access from WSL terminal, create a helper script:\n\n```bash\n#!/bin/bash\nCURRENT_PATH=$(readlink -f \"$1\")\nwindsurf --folder-uri \"vscode-remote://wsl+Ubuntu$CURRENT_PATH\"\n```\n\n### Authentication\n\nSign up or log in to your Windsurf (formerly Codeium) account during onboarding or via the profile menu.\n\n## Cascade — The AI Agent\n\nCascade 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.\n\n### Cascade Modes\n\nCascade comes in two primary modes:\n\n- **Write Mode** (`Cmd+L` / `Ctrl+L`): Full write access — creates files, edits code, runs terminal commands, and makes modifications to your codebase.\n- **Chat Mode** (`Cmd+Shift+L` / `Ctrl+Shift+L` to toggle): Read-only — answers questions about your codebase and general coding principles without making changes.\n\n### Model Selection\n\nSwitch between models from the dropdown below the Cascade input box. Available models include:\n\n- **SWE-1.5** (Windsurf's own near-frontier model, free for all users)\n- **Claude Opus 4.6**, Claude Sonnet 4.5\n- **GPT-5.2**, GPT-5.2-Codex, GPT-5.1, GPT-5.1-Codex\n- **Gemini 3 Flash**, Gemini 3 Pro\n- **Falcon Alpha** (stealth model, speed-optimized)\n- **BYOK** (Bring Your Own Key) for custom models\n\nEach prompt consumes credits depending on the model selected.\n\n### Tool Calling\n\nCascade has a variety of built-in tools:\n\n- **Search**: Semantic code search across your repository\n- **Analyze**: Deep analysis of code structure and relationships\n- **Web Search**: Search the web for documentation and references\n- **MCP**: Call external tools via Model Context Protocol\n- **Terminal**: Execute shell commands directly\n\nCascade can make up to **25 tool calls per prompt**. If the trajectory stops, type `continue` and Cascade will resume.\n\n### Context Selection with @ Mentions\n\nReference specific files, functions, or context in your prompts:\n\n```\n@filename.ts\n@src/components/\n@function:calculateTotal\n```\n\nYou can also:\n- Drag and drop files from the File Explorer into Cascade\n- Send problems from the Problems panel to Cascade\n- Highlight errors and click \"Explain and Fix\"\n- @-mention previous conversations for cross-session context\n\n### Voice Input\n\nUse voice input to interact with Cascade via speech-to-text transcription.\n\n### Checkpoints and Reverts\n\nCascade 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.**\n\n## Keyboard Shortcuts\n\n| Action | macOS | Windows/Linux |\n|---|---|---|\n| Open Cascade (Write) | `Cmd+L` | `Ctrl+L` |\n| Toggle Write/Chat | `Cmd+Shift+L` | `Ctrl+Shift+L` |\n| Command Palette | `Cmd+Shift+P` | `Ctrl+Shift+P` |\n| Inline AI (terminal) | `Cmd+I` | `Ctrl+I` |\n| Accept focused diff hunk | `Option+Enter` | `Alt+Enter` |\n| Reject focused diff hunk | `Option+Shift+Backspace` | `Alt+Shift+Backspace` |\n| Fast Context (first msg) | `Cmd+Enter` | `Ctrl+Enter` |\n\n## Skills\n\nSkills let you bundle instructions, templates, checklists, and supporting files into folders that Cascade can invoke for complex, multi-step tasks.\n\n### Creating a Skill\n\n1. Click the Customizations icon in Cascade's top-right slider menu\n2. Navigate to the Skills panel\n3. Click `+ Workspace` (project-specific) or `+ Global`\n4. Name the skill (lowercase letters, numbers, hyphens only)\n\n### Skill Structure\n\nEach skill is a folder with a `SKILL.md` file and optional supporting files:\n\n```\n.windsurf/skills/deploy-to-production/\n├── SKILL.md\n├── deployment-checklist.md\n├── rollback-procedure.md\n└── config-template.yaml\n```\n\n### SKILL.md Format\n\n```markdown\n---\nname: deploy-to-production\ndescription: Guides the deployment process to production with safety checks\n---\n\n## Pre-deployment Checklist\n1. Run all tests\n2. Check for pending migrations\n3. Verify environment variables\n...\n```\n\nThe `name` field is used for display and @-mentions. The `description` helps Cascade decide when to automatically invoke the skill.\n\n### Invoking Skills\n\n- **Automatic**: Cascade uses progressive disclosure to invoke skills when they're relevant to your task\n- **Manual**: @-mention the skill name in your prompt\n\nFor the full Skills specification, visit [agentskills.io](https://agentskills.io).\n\n## Workflows\n\nWorkflows define a series of steps to guide Cascade through repetitive tasks. They are saved as markdown files and invoked via slash commands.\n\n### Creating a Workflow\n\n1. Click Customizations icon → Workflows panel → `+ Workflow`\n2. Or ask Cascade to generate a Workflow for you\n\n### Workflow Storage\n\nWorkflows are saved in `.windsurf/workflows/` directories. Windsurf discovers them from:\n- Current workspace and sub-directories\n- Parent directories up to the git root (for git repos)\n- Multiple workspace support with deduplication\n\nWorkflow files are limited to **12,000 characters** each.\n\n### Invoking Workflows\n\n```\n/workflow-name\n```\n\nWorkflows can call other workflows:\n\n```markdown\n## Steps\n1. Call /lint-and-format\n2. Call /run-tests\n3. Deploy to staging\n```\n\n### Example Workflow — PR Review\n\n```markdown\n---\nname: pr-review\ndescription: Review PR comments and address them\n---\n\n## Steps\n1. Check out the PR branch: `gh pr checkout [id]`\n2. Get comments on PR:\n   ```bash\n   gh api --paginate repos/[owner]/[repo]/pulls/[id]/comments | jq '.[] | {user: .user.login, body, path, line}'\n   ```\n3. For EACH comment, address the feedback and commit the fix\n4. Push changes and reply to each comment\n```\n\n## Memories & Rules\n\nMemories persist context across Cascade conversations. Rules guide Cascade behavior.\n\n### Memories\n\n- **Auto-generated**: Cascade creates memories when it encounters useful context. Does NOT consume credits.\n- **User-created**: Type `create memory ...` in Cascade to manually save context.\n- Auto-generated memories are workspace-specific.\n\n**Managing Memories:**\n- Windsurf Settings → Settings tab → Manage next to \"Cascade-Generated Memories\"\n- Or: three dots in Cascade → Manage Memories\n- Toggle auto-generation: Settings → \"Auto-Generate Memories\"\n\n### Rules\n\nRules are manually defined instructions for Cascade.\n\n**Rule Levels:**\n- `global_rules.md` — applies across all workspaces\n- `.windsurf/rules/` — workspace-level directory with rules tied to globs or descriptions\n- System-level rules (Enterprise) — deployed via MDM policies\n\n**Activation Modes:**\n- **Always**: Rule is always active\n- **Glob**: Applied to files matching a pattern (e.g., `*.js`, `src/**/*.ts`)\n- **Manual / Description-based**: Activated by natural language match\n\n**Rules Best Practices:**\n- Keep rules simple, concise, and specific\n- Use bullet points and markdown formatting\n- Avoid generic rules like \"write good code\"\n- Use XML tags to group similar rules\n\n**Example Rule:**\n\n```markdown\n# Coding Guidelines\n- My project's programming language is Python\n- Use early returns when possible\n- Always add documentation when creating new functions and classes\n- Use pytest for testing\n- Follow PEP 8 style guide\n```\n\n## Terminal Integration\n\n### Inline AI Terminal\n\nPress `Cmd+I` / `Ctrl+I` in the terminal to access an inline chat box that generates CLI commands from natural language.\n\n### Cascade Terminal Execution\n\nCascade can run terminal commands directly. Configure auto-execution levels in Windsurf Settings:\n\n1. **Manual**: Always ask for permission (default)\n2. **Semi-auto**: Auto-run safe commands\n3. **Turbo Mode**: Auto-execute all commands without confirmation\n4. **Custom**: Use Allow/Deny lists for specific commands\n\n### Dedicated Terminal (Wave 13)\n\nWindsurf uses a dedicated zsh shell for Cascade command execution, providing improved reliability. It uses your `.zshrc` environment variables and is fully interactive.\n\n### ⚠️ Using with AI Agents / Automation\n\nWhen running Windsurf from automated environments (AI agents, scripts, orchestrators), the IDE requires a GUI context. For headless automation scenarios, consider:\n\n1. **Using Windsurf's Workflows**: Define multi-step tasks as Workflows that Cascade executes\n2. **MCP Integration**: Connect external automation tools via MCP servers\n3. **Cascade Hooks**: Execute custom shell commands at key points in Cascade's workflow\n\n## MCP Integration\n\nWindsurf supports Model Context Protocol (MCP) for connecting external tools and services.\n\n### Configuration\n\nConfigure MCP servers in `mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"uvx\",\n      \"args\": [\"github-mcp\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\nAccess via: Windsurf Settings → Cascade → Manage MCPs → View raw config\n\n### MCP Features\n\n- **MCP Marketplace**: Browse curated servers in Windsurf Settings for one-click setup\n- **@ Mentions**: Trigger MCP tools by @-mentioning in Cascade\n- **Enable/Disable**: Toggle MCP servers from the Cascade header\n- **Transports**: Supports stdio, Streamable HTTP, and SSE\n- **Enterprise**: Team admins can whitelist/blacklist MCP servers\n\nEach MCP tool call costs one prompt credit.\n\n## Cascade Hooks\n\nExecute custom shell commands at key points during Cascade's workflow:\n\n- **On model response**: For logging, auditing, security controls\n- **Pre/Post hooks**: For validation and governance (Enterprise)\n\n## Simultaneous Cascades\n\nRun multiple Cascade sessions in parallel:\n\n- Open side-by-side Cascade panes\n- Use Git worktrees to work on different branches without conflicts\n- Start work in a new Cascade while another is executing\n\n## Fast Context\n\nPress `Cmd+Enter` / `Ctrl+Enter` on the first message to enable Fast Context. Uses SWE-grep models for up to 20x faster code retrieval from large codebases.\n\n## Ignoring Files\n\nAdd files to `.codeiumignore` at the root of your workspace (same syntax as `.gitignore`). For global ignore rules across all repositories, place `.codeiumignore` in `~/.codeium/`.\n\n## Workflows (Common Use Cases)\n\n### Code Review\n\n```\nReview the changes in the current branch against main.\nFocus on security and performance.\n```\n\n### Refactoring\n\n```\nRefactor src/utils.ts to reduce complexity and improve type safety.\n```\n\n### Debugging\n\n```\nAnalyze the following error log and suggest a fix: [paste error]\n```\n\nOr: Highlight error → \"Explain and Fix\"\n\n### Git Integration\n\n```\nGenerate a commit message for the staged changes adhering to conventional commits.\n```\n\n### Deployment\n\nCreate a Workflow in `.windsurf/workflows/deploy.md`:\n\n```markdown\n---\nname: deploy\ndescription: Deploy to production with safety checks\n---\n\n## Steps\n1. Run all tests: `npm test`\n2. Build the project: `npm run build`\n3. Run linter: `npm run lint`\n4. If all pass, deploy: `npm run deploy:production`\n5. Verify deployment health checks\n```\n\nInvoke with `/deploy` in Cascade.\n\n### Live Preview\n\nWindsurf has built-in live preview for web apps. Ask Cascade to start a dev server and preview will appear inside the editor. Click any element to let Cascade reshape it.\n\n### App Deploy\n\nDeploy your app with one click via Cascade tool calls (beta Netlify deployment support).\n\n## Pricing\n\n| Plan | Price | Credits/month | Best For |\n|---|---|---|---|\n| Free | $0 | 25 | Students, hobbyists |\n| Pro | $15/mo | 500 | Individual developers |\n| Teams | $30/user/mo | Custom | Development teams |\n| Enterprise | $60/user/mo | Custom | Large organizations |\n\n## Key Differences from Cursor\n\n| Feature | Windsurf | Cursor |\n|---|---|---|\n| AI Agent | Cascade (agentic, flow-aware) | Cursor Agent (CLI-based) |\n| Rules | `.windsurf/rules/` + `global_rules.md` | `.cursor/rules` + `CLAUDE.md` |\n| Workflows | `.windsurf/workflows/` (slash commands) | N/A (manual) |\n| Memories | Auto-generated + user-created | Codebase indexing + Project Rules |\n| Skills | `.windsurf/skills/` (bundled folders) | N/A |\n| Terminal | Dedicated zsh shell + Turbo Mode | Standard terminal |\n| Live Preview | Built-in | Extension-based |\n| MCP | Native with marketplace | Native |\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":328,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1771377924300,"updatedAt":1778991338284},"latestVersion":{"version":"1.0.0","createdAt":1771377924300,"changelog":"Initial public release — comprehensive skillset for Windsurf IDE and Cascade agent with full 2026 feature support.\n\n- Provides detailed installation and setup instructions, including Windows WSL and configuration import.\n- Documents Cascade agent's modes, capabilities (write/chat), tool calling (up to 25 calls per prompt), and model selection.\n- Explains skills and workflow creation, storage, invocation, and Cascades' context management (memories and rules).\n- Lists keyboard shortcuts and user interaction options (voice input, checkpoints, reverts).\n- Covers advanced features like MCP integration, multi-agent sessions, and context management through @-mentions.\n- Includes best practices for incorporating Skills, Workflows, and persistent context in software engineering tasks.","license":null},"metadata":null,"owner":{"handle":"lucaslcarrijo","userId":"s170x0kejphvqbbgmyq5cjp2cx88453z","displayName":"LucasLCarrijo","image":"https://avatars.githubusercontent.com/u/124224248?v=4"},"moderation":null}