Windsurf Skills: How to Add SKILL.md to Windsurf Editor (2026)

Quick Answer: Windsurf Editor supports SKILL.md skills through its Cascade agent mode. Place skills in .windsurf/skills/ in your project directory. Windsurf reads the YAML frontmatter and activates skills based on task relevance. The same SKILL.md files that work in Claude Code and Cursor work in Windsurf without modification.

---

Windsurf Editor is one of the fastest-growing AI-powered IDEs in 2026. Built by Codeium (now Windsurf), it combines chat, autocomplete, and agentic code actions into a single editor. Its Cascade feature handles multi-step tasks autonomously, making it a direct competitor to Cursor and Claude Code's VS Code extension.

What most Windsurf users don't know: Cascade supports SKILL.md skills. You can teach it custom workflows, coding conventions, and structured procedures using the same portable skill format that works across 20+ AI coding agents.

Where Windsurf stores skills

Windsurf reads skills from your project directory:

your-project/
├── .windsurf/
│   └── skills/
│       ├── code-reviewer/
│       │   └── SKILL.md
│       └── test-generator/
│           └── SKILL.md
├── src/
└── package.json

Like Cursor, Windsurf focuses on project-scoped skills. There's no global skills directory. If you want the same skill in every project, copy it into each project's .windsurf/skills/ folder or use a script to automate the setup.

Recommended skills

designing-hybrid-context-layers

by https://loreto.io · 16

Architects the right retrieval strategy for every query — teaching your agent wh…

$10

ai-automation-qa-pack

by Roy Yuen · 10

Professional QA & UAT documentation generator for AI automation agencies and com…

$5

Bounty Security Pattern Master Library — 399 Vulnerability Patterns

by Atlas Agent Suite · 9

A premium library of 399 vulnerability patterns and DeFi attack vectors for AI-d…

$75

Browse all Windsurf skills

How to install skills in Windsurf

From Agensi (one command)

mkdir -p .windsurf/skills && curl -sL https://www.agensi.io/api/install/code-reviewer | tar xz -C .windsurf/skills/

From a zip download

unzip code-reviewer.zip -d .windsurf/skills/

From GitHub

git clone https://github.com/author/skill-name.git
cp -r skill-name .windsurf/skills/

After installing, reload your Windsurf workspace. Cascade picks up new skills on the next interaction.

How Windsurf uses SKILL.md skills

Windsurf's Cascade reads the description field in the YAML frontmatter to decide when to activate a skill. When you ask Cascade to review code and you have a code-reviewer skill installed, it loads the skill's instructions and follows them.

This works the same way as Claude Code and Cursor. The portable SKILL.md format means no per-agent customization needed.

What works in Windsurf

The core SKILL.md features all work:

• name and description frontmatter fields for identification and activation
• when_to_use for extended trigger guidance
• Markdown body with structured instructions
• Supporting files in scripts/, references/, and assets/ subdirectories

What doesn't transfer

Agent-specific frontmatter fields like Claude Code's context: fork and allowed-tools are ignored by Windsurf. These are safely skipped without causing errors. If your skill relies heavily on subagent spawning or tool restrictions, the behavior will differ in Windsurf.

Windsurf vs Cursor vs Claude Code for skills

The key difference: Claude Code has both global and project-scoped skills. Windsurf and Cursor only support project-scoped. This means Claude Code users can maintain a personal skill library, while Windsurf users need to install skills per project.

How .windsurfrules relates to SKILL.md

Windsurf has .windsurfrules, similar to Cursor's .cursorrules. This file provides always-on project context (coding conventions, framework choices, style preferences).

The relationship between .windsurfrules and SKILL.md is the same as .cursorrules and SKILL.md: use the rules file for general project context that applies to every interaction, and use skills for specific task workflows that activate only when relevant.

Don't put workflow instructions in .windsurfrules. That bloats the always-on context and wastes tokens. Keep .windsurfrules short and put detailed procedures in SKILL.md skills.

Sharing skills across agents

If you use both Windsurf and Claude Code (or Cursor, or Codex CLI), the same skill files work in all of them:

# Copy from Claude Code to Windsurf
cp -r ~/.claude/skills/code-reviewer .windsurf/skills/

# Copy from Windsurf to Cursor
cp -r .windsurf/skills/code-reviewer .cursor/skills/

Or use symlinks if you want a single source of truth:

ln -s ~/.claude/skills .windsurf/skills

Getting started

1. Create .windsurf/skills/ in your project
2. Install 2-3 skills that match your daily workflow from Agensi
3. Reload Windsurf
4. Ask Cascade to do something that matches a skill's description
5. Verify the output follows the skill's structure

For a full comparison of config file formats, read AGENTS.md vs SKILL.md vs CLAUDE.md vs .cursorrules.

---

Browse 300+ security-scanned skills compatible with Windsurf, Claude Code, Cursor, and 20+ agents at agensi.io/skills.