Windsurf Known Pitfalls

What it does

When your agent uses it

• Onboarding new developers to Windsurf
• Reviewing AI workflow practices
• Auditing Windsurf configuration for issues
• With phrases like windsurf mistakes

Example prompts

• “windsurf mistakes”
• “windsurf anti-patterns”
• “windsurf pitfalls”
• “/windsurf-known-pitfalls”

Requirements

• Compatibility (from SKILL.md): Designed for Claude Code
• Pre-approved tools (allowed-tools): Read, Grep

Workflow steps

10 steps, taken from the step headings in SKILL.md.

1. 1Avoid Using Cascade for Simple Tasks
2. 2Avoid Opening a Monorepo Root
3. 3Replace Vague Cascade Prompts
4. 4Review Every Proposed Change
5. 5Create a Checkpoint Before Cascade
6. 6Isolate Conflicting AI Extensions
7. 7Respect Rule Character Limits
8. 8Bound Cascade Conversations
9. 9Keep Secrets Out of Cascade
10. 10Configure Turbo Mode Safely

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Grep

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • git

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • docs.devin.ai
  • windsurf.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Designed for Claude Code

  From compatibility in the SKILL.md frontmatter.

Context cost

Windsurf Known Pitfalls loads about 2.3k tokens when it runs, and up to ~2.4k if it reads all its reference files. Until then it costs about 95 tokens; SKILL.md has 474 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~95

When it runs · the whole SKILL.md, loaded when a task matches

~2.3k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:188

  etting auth errors with the API key from .env. The error

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 474 words, ~2,297 tokens.

name

windsurf-known-pitfalls

description

Identify and avoid Devin Desktop (formerly Windsurf) anti-patterns and common mistakes. Use when onboarding new developers to Windsurf, reviewing AI workflow practices, or auditing Windsurf configuration for issues. Trigger with phrases like "windsurf mistakes", "windsurf anti-patterns", "windsurf pitfalls", "windsurf what not to do", "windsurf gotchas".

allowed-tools

Read, Grep

compatibility

Designed for Claude Code

argument-hint

[scope or requirements]

version

1.12.0

license

MIT

author

Jeremy Longshore <jeremy@intentsolutions.io>

tags

saas, windsurf, anti-patterns, gotchas, best-practices

BAD: Opening Cascade to write "add a console.log"
→ Cascade spins up full agent context, reads multiple files = slow and expensive

GOOD: Use Supercomplete (Tab) for inline completions
→ Instant; verify the current model's usage label before assuming no quota charge

RULE OF THUMB:
- Single line / simple completion → Tab (Supercomplete)
- Inline edit of selection → Cmd+I (Command)
- Multi-file task / complex reasoning → Cmd+L (Cascade)

BAD:  windsurf ~/company-monorepo/
→ Cascade indexes everything, slow context, vague suggestions

GOOD: windsurf ~/company-monorepo/services/payments/
→ Focused context, fast indexing, precise suggestions

WHY: Cascade's context window is limited. More files = more noise.
A focused workspace with 5K files gives better suggestions than
a bloated workspace with 100K files.

BAD: "Refactor the codebase to use TypeScript"
→ Cascade may try to convert EVERY file at once, breaking everything

BAD: "Add validation to the API"
→ Which API? Which endpoints? What validation rules?

GOOD: "Convert src/utils/api.js to TypeScript. Add proper types for
all function parameters and return values. Don't change other files."

GOOD: "In src/routes/users.ts, add zod validation for the POST /users
endpoint. Validate email format, name length (2-50 chars), and role
must be 'admin' or 'user'. Return 400 with field-level errors."

BAD: Cascade modifies 12 files → "Accept All" → broken tests
→ Cascade may have changed shared utilities, removed error handling,
  or introduced dependencies on APIs that don't exist

GOOD:
1. Read Cascade's explanation of what it changed
2. Review each file diff in the Cascade output
3. Check for: removed error handling, new imports, changed signatures
4. Run tests BEFORE committing
5. Use revert button if any file looks wrong

BAD: Uncomitted changes + Cascade edits = impossible to separate
→ Can't tell what was your work vs what Cascade changed
→ Can't revert Cascade changes without losing your work

GOOD: git add -A && git commit -m "checkpoint: before cascade"
→ Clean separation between your work and Cascade's
→ Easy revert: git checkout -- .

KNOWN CONFLICTS:
- GitHub Copilot — conflicts with Supercomplete
  Symptoms: duplicate suggestions, wrong completions, slow editor

- TabNine — conflicts with Supercomplete
  Symptoms: competing inline suggestions

- Cody (Sourcegraph) — conflicts with Cascade
  Symptoms: multiple AI panels, context confusion

FIX: Disable competing extensions
Settings > Extensions > search "copilot" > Disable

BAD: 50-message Cascade conversation spanning multiple topics
→ Context window fills up, Cascade "forgets" early context
→ Suggestions become inconsistent or contradictory

GOOD: One task per Cascade session
→ Click + icon to start new conversation for each new task
→ Clean context = better suggestions
→ Use Memories for facts that should persist across sessions

BAD: "My API key is sk-abc123def456, why isn't auth working?"
→ Secret is now in Cascade's context, may appear in suggestions later

GOOD: "I'm getting auth errors with the API key from .env. The error
message is 'Invalid API key'. What should I check?"
→ Cascade can help without seeing the actual secret

BAD: Turbo mode ON + no deny list
→ Cascade auto-runs `rm -rf`, `git push --force`, etc.

GOOD: Turbo mode ON + configured deny list
→ Fast auto-execution for safe commands (npm test, git status)
→ Manual approval for dangerous commands (rm, sudo, push --force)

CONFIGURE:
Settings > cascadeCommandsDenyList > add destructive commands

set -euo pipefail
echo "=== Pre-Cascade Checklist ==="
readonly WORKSPACE_RULE_LIMIT=12000 # Current documented maximum for one workspace rule.
echo "Git clean: $(git status --porcelain | wc -l | xargs) uncommitted files"
echo "On branch: $(git branch --show-current)"
echo "Rules: $(wc -c < .devin/rules/project.md 2>/dev/null || echo 0) chars (max $WORKSPACE_RULE_LIMIT)"
echo "Conflicting exts: $(windsurf --list-extensions 2>/dev/null | grep -ci 'copilot\|tabnine\|cody' || echo 0)"

Feature: "In [file], add [feature] that [behavior]. Follow the pattern
in @[reference-file]. Include error handling for [edge cases]. Don't
modify [protected files]."

Bug fix: "@[file] The function [name] fails when [condition]. The error
is [error message]. Fix it and add a test for this edge case."

Refactor: "Extract [logic] from [file] into a new [file]. Update all
imports. Run tests after. Don't change public API signatures."

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in skills/.curated/windsurf-known-pitfalls of jeremylongshore/tons-of-skills-marketplace.

• SKILL.md
• references/official-docs.md

Open the folder on GitHubat commit cfae287