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

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.

Skills to install right now

code-reviewer

Free

Run a structured code review on your recent changes without waiting for a teammate. This skill checks for security vulnerabilities (SQL injection, XSS, authentication bypasses), logic errors, edge cases, performance issues, and style violations.Findings are organized by severity: Critical, Warning, and Suggestion. Each finding includes the file, line number, a description of the issue, and a concrete fix. Use it as a first pass before peer review, or as your only reviewer on solo projects.

Get this skill

git-commit-writer

Free

Stop writing vague commit messages. This skill reads your actual staged diff and generates precise, informative commit messages following the Conventional Commits specification. It detects the commit type (feat, fix, refactor, docs, chore, etc.), identifies the scope from the changed files, flags breaking changes, and suggests splitting commits when multiple logical changes are staged. Works with any git repository.`

Get this skill

readme-generator

Free

Point this skill at any project and it generates a real README from your actual codebase. It scans package.json, pyproject.toml, Cargo.toml, or equivalent to detect your language, framework, and dependencies. It reads your .env.example for setup instructions, checks for Dockerfiles and CI config, and produces a README with only the sections that apply to your project. No placeholder text, no generic filler. Every line is derived from what it actually finds in your repo.

Get this skill

Browse all 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.