How to Build a Plugin Strategy for Windsurf

Build a Windsurf plugin strategy with SKILL.md capabilities: write the Skill, place it in .windsurf/skills, preserve plugin identity, and measure it with Telvine.

This guide shows how to build a plugin strategy for Windsurf, the agentic code editor. Windsurf's Cascade agent loads agent Skills defined in a SKILL.md, so treat the Skill as one capability inside a plugin product that you version and measure.

Step 1 — Write the SKILL.md

---
name: api-client-generator
description: >
  Use this skill when the user asks to "generate an API client",
  "create a client from this spec", or "wrap this endpoint".
  Generates a typed client from an API spec in the repo's style.
---
 
# API client generator
## Steps
1. Read the API spec and an existing client for style.
2. Generate a typed client with error handling.
3. Add minimal usage docs. Don't touch unrelated modules.

The description — third person, with the exact phrases users say — is what makes Cascade reach for the Skill.

Step 2 — Place it in .windsurf/skills

Create a .windsurf/skills/ directory in your project and add a folder per Skill:

your-project/
└── .windsurf/skills/
    └── api-client-generator/
        └── SKILL.md

The same SKILL.md files that work in Claude Code and Cursor work in Windsurf without modification.

Step 3 — Trigger it in Cascade

Open Cascade and describe the task. When the request matches the Skill's description, Cascade loads the SKILL.md and follows it. If it doesn't trigger, refine the description first. Keep deterministic steps in bundled scripts/.

Step 4 — Measure it with Telvine

Telvine tracks installs, invocations, errors, and latency for your Windsurf Skills, compares versions with significance testing, and pipes events to your stack — using a closed event envelope that never carries prompts or code. Wrap the SKILL.md once and you'll know whether each version is an improvement.

Write once, run in any harness

A Skill written for Windsurf also runs in Claude Code, Codex, Copilot, Cursor, and Gemini CLI — it's the same SKILL.md. Maintain one Skill and measure it in one place.

Frequently asked questions

Where do Windsurf Skills go? In the .windsurf/skills/ directory of your project; Cascade loads them on demand.

Can I reuse a Skill from another agent in Windsurf? Yes — the same SKILL.md works in Windsurf without modification.