windsurf-webhooks-events — Claude Code skill: events and setup
The windsurf-webhooks-events skill guides you through building Windsurf extensions with the VS Code API and forwarding workspace events to an external service. Use it to track saves, editor changes, or terminal output.
MIT 1 installs ★ 2,935 updated 2026-10-29
npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a claude-codeWhat windsurf-webhooks-events does
The skill walks through a Windsurf extension that responds to file saves, active-editor changes, and terminal output. It shows how to send workspace events as JSON to a webhook, with a delay for frequent events. The examples also cover extension settings and a status command.
You need Node.js 18+, npm, familiarity with the VS Code Extension API, and Windsurf for testing. Build with npm run compile and package the extension as a .vsix using npx vsce package. API compatibility depends on the VS Code version, so check engines.vscode against the Windsurf version you plan to target.
What it helps with
- build a TypeScript extension for Windsurf
- track file saves and active-editor changes
- send workspace events to a webhook
- respond to errors in terminal output
Example prompts for the agent
- Build a TypeScript Windsurf extension that tracks file saves and displays the number of diagnostic errors.
- Add webhook delivery for workspace events and make the URL configurable in extension settings.
- Check terminal error handling and prepare a
.vsixpackage for Windsurf.
How to install windsurf-webhooks-events
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a claude-code2Manually: put the files in place
~/.claude/skills/windsurf-webhooks-events/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/windsurf-webhooks-events/
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a codex2Manually: put the files in place
.agents/skills/windsurf-webhooks-events/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a cursor2Manually: put the files in place
.cursor/skills/windsurf-webhooks-events/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jeremylongshore/tons-of-skills-marketplace skills/.curated/windsurf-webhooks-events2Manually: put the files in place
.github/skills/windsurf-webhooks-events/SKILL.md1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a gemini-cli2Platform CLI
gemini skills install https://github.com/jeremylongshore/tons-of-skills-marketplace --path skills/.curated/windsurf-webhooks-eventsManually: put the files in place
.devin/skills/windsurf-webhooks-events/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about windsurf-webhooks-events
How do I install windsurf-webhooks-events in Claude Code?
Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a claude-code. The skill file will be at ~/.claude/skills/windsurf-webhooks-events/SKILL.md.
What does windsurf-webhooks-events do?
It guides development of Windsurf extensions based on the VS Code API, including tracking editor events and sending them to an external service through a webhook.
What do I need to build an extension with this skill?
You need Node.js 18+, npm, familiarity with the VS Code Extension API, and Windsurf for testing.
Source text
SKILL.md · MIT
--- name: windsurf-webhooks-events description: 'Build Devin Desktop (formerly Windsurf) extensions and integrate with VS Code extension API events. Use when building custom Windsurf extensions, tracking editor events, or integrating Windsurf with external tools via extension development. Trigger with phrases like "windsurf extension", "windsurf events", "windsurf plugin", "build windsurf extension", "windsurf API". ' allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*) argument-hint: "[scope or requirements]" version: 1.12.0 license: MIT author: Jeremy Longshore <[email protected]> tags: - saas - windsurf - extensions - vscode-api - development compatibility: Designed for Claude Code --- # Windsurf Extension Development & Events ## Overview Build compatible extensions on Devin Desktop's VS Code foundation to observe workspace events and integrate external tools. Keep telemetry, credential, network, and user-consent boundaries explicit instead of assuming every VS Code behavior is product-guaranteed. ## Prerequisites - Node.js 18+ and npm - VS Code Extension API familiarity - `yo` and `generator-code` for scaffolding - Windsurf IDE for testing ## Tool Use - Use `Read` to inspect only the repository files and configuration needed for the request. - Use `Write` only for a new artifact the user requested; never write credentials or unreviewed production configuration. - Use `Edit` for bounded, reviewable changes and preserve unrelated user work. - Use only the command-scoped `Bash` entries declared in frontmatter, with non-destructive checks before mutations. ## Instructions ### Step 1: Scaffold Extension ```bash # Install scaffolding tools npm install -g yo generator-code # Generate extension yo code # Select: New Extension (TypeScript) # Name: my-windsurf-extension ``` ### Step 2: Track Workspace Events ```typescript // src/extension.ts import * as vscode from "vscode"; export function activate(context: vscode.ExtensionContext) { console.log("Extension active in Windsurf"); // Track file saves const saveListener = vscode.workspace.onDidSaveTextDocument( async (document) => { const diagnostics = vscode.languages.getDiagnostics(document.uri); const errors = diagnostics.filter( (d) => d.severity === vscode.DiagnosticSeverity.Error ); if (errors.length > 0) { vscode.window.showWarningMessage( `${document.fileName}: ${errors.length} error(s) after save` ); } } ); // Track active editor changes const editorListener = vscode.window.onDidChangeActiveTextEditor( (editor) => { if (editor) { const lang = editor.document.languageId; const lines = editor.document.lineCount; console.log(`Opened: ${editor.document.fileName} (${lang}, ${lines} lines)`); } } ); // Track terminal output const terminalListener = vscode.window.onDidWriteTerminalData((event) => { // Can monitor for specific patterns (errors, warnings) if (event.data.includes("ERROR") || event.data.includes("FAIL")) { vscode.window.showWarningMessage("Error detected in terminal output"); } }); context.subscriptions.push(saveListener, editorListener, terminalListener); } ``` ### Step 3: Send Events to External System ```typescript // src/webhook.ts import * as vscode from "vscode"; interface WorkspaceEvent { event: string; file?: string; language?: string; timestamp: string; metadata?: Record<string, unknown>; } async function sendEvent(event: WorkspaceEvent): Promise<void> { const webhookUrl = vscode.workspace .getConfiguration("windsurf-events") .get<string>("webhookUrl"); if (!webhookUrl) return; try { await fetch(webhookUrl, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(event), }); } catch (err) { console.warn("Webhook delivery failed:", err); } } // Debounce frequent events const debounceMap = new Map<string, NodeJS.Timeout>(); function debouncedSend(event: WorkspaceEvent, delayMs = 2000): void { const key = `${event.event}:${event.file}`; clearTimeout(debounceMap.get(key)); debounceMap.set( key, setTimeout(() => { sendEvent(event); debounceMap.delete(key); }, delayMs) ); } ``` ### Step 4: Extension package.json ```json { "name": "windsurf-events", "displayName": "Windsurf Events", "version": "1.0.0", "engines": { "vscode": "^1.85.0" }, "activationEvents": ["onStartupFinished"], "main": "./dist/extension.js", "contributes": { "configuration": { "title": "Windsurf Events", "properties": { "windsurf-events.webhookUrl": { "type": "string", "description": "URL to send workspace events to" }, "windsurf-events.trackSaves": { "type": "boolean", "default": true, "description": "Track file save events" }, "windsurf-events.trackErrors": { "type": "boolean", "default": true, "description": "Track terminal error events" } } }, "commands": [ { "command": "windsurf-events.showStatus", "title": "Windsurf Events: Show Status" } ] } } ``` ### Step 5: Build and Install ```bash # Build npm run compile # or: npm run build # Package as .vsix npx vsce package # Install in Windsurf windsurf --install-extension windsurf-events-1.0.0.vsix # Or publish to marketplace npx vsce publish ``` ### Step 6: Test in Windsurf ``` 1. Open Extension Development Host: F5 in Windsurf 2. A new Windsurf window opens with extension loaded 3. Open a file, save it, trigger events 4. Check Output panel > "Windsurf Events" channel 5. Verify webhook delivery (use https://webhook.site for testing) ``` ## Output Produce a reviewed VS Code-compatible extension change with event subscriptions, disposal lifecycle, authentication and secret storage, payload schema, retry behavior, local test evidence, package metadata, and marketplace compatibility notes. Do not log raw credentials or proprietary source. ## Error Handling | Issue | Cause | Solution | |-------|-------|----------| | Extension not activating | Wrong `activationEvents` | Use `onStartupFinished` for always-on | | Webhook fails | Network/URL issue | Queue locally, retry with backoff | | High CPU usage | Too many listeners | Debounce frequent events (saves, edits) | | API incompatibility | Windsurf vs VS Code version | Pin `engines.vscode` version | | `vsce package` fails | Missing fields | Add publisher, repository, license | ## Examples ### Team Analytics Extension ```typescript // Track AI acceptance rate per developer vscode.languages.registerInlineCompletionItemProvider( { pattern: "**" }, { provideInlineCompletionItems(document, position) { // Log completion requests (don't interfere with Supercomplete) console.log(`Completion at ${document.fileName}:${position.line}`); return []; // Return empty -- let Windsurf handle completions } } ); ``` ### Quick Test Webhook ```bash # Start a test webhook receiver npx -y webhook-relay -p 3456 # Configure extension: windsurf-events.webhookUrl = "http://localhost:3456" ``` ## Resources - [Focused first-party references](references/official-docs.md) - [VS Code Extension API](https://code.visualstudio.com/api) - [VS Code Extension Publishing](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) - [Windsurf Marketplace](https://marketplace.windsurf.com) ## Related Skill Continue with `windsurf-multi-env-setup` to package extension settings, event destinations, and environment-specific policies for repeatable team rollout.
© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace