Skip to main content
The Windsurf converter creates skills (from agents) and workflows (from commands) with support for global and workspace scopes.

​
Installation

​
Global Scope (default)

bunx @every-env/compound-plugin install compound-engineering --to windsurf
Writes to ~/.codeium/windsurf/: 
~/.codeium/windsurf/
├── skills/
│   ├── agent-name/
│   │   └── SKILL.md          # Agent skills
│   └── existing-skill/       # Pass-through skills
├── global_workflows/
│   └── *.md                  # Command workflows (global)
└── mcp_config.json           # MCP server config

​
Workspace Scope

bunx @every-env/compound-plugin install compound-engineering --to windsurf --scope workspace
Writes to .windsurf/ in your project: 
.windsurf/
├── skills/
├── workflows/                # Command workflows (workspace)
└── mcp_config.json
The only difference between scopes is the workflows directory: global_workflows/ for global, workflows/ for workspace.

​
Conversion Details

​
Agents → Skills

Agents are converted to skills: 
---
name: plan-specialist
description: Planning agent for complex features
---

# plan-specialist

## Capabilities
- Break down complex features
- Create detailed plans

You are a planning specialist...

​
Commands → Workflows

Commands become workflows: 
---
description: Turn feature ideas into detailed plans
---

# workflows-plan

> Arguments: <feature description>

You are a planning specialist. Use the @repo-research-analyst skill: research the feature.
Invocation: 
/workflows-plan
Workflow content is limited to 12,000 characters. Longer workflows may be truncated by Windsurf.

​
Content Transformation

Task agent calls: 
- Task repo-research-analyst(feature_description)
+ Use the @repo-research-analyst skill: feature_description
Slash command refs: 
- Run /workflows:plan
+ Run /workflows-plan
Agent references: 
- No transformation needed
+ @agent-name is native Windsurf skill syntax
Path rewriting: 
- ~/.claude/skills/
+ ~/.codeium/windsurf/skills/
- .claude/
+ .windsurf/

​
MCP Servers

MCP servers are merged into mcp_config.json: 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/you/projects"
      }
    },
    "remote-api": {
      "serverUrl": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN}"
      }
    }
  }
}
Stdio servers:
  • command: Executable path
  • args: Command arguments
  • env: Environment variables
Remote servers:
  • serverUrl: HTTP endpoint (mapped from url)
  • headers: HTTP headers
  • env: Environment variables
Existing mcp_config.json is preserved. Plugin servers are merged with existing entries taking precedence.

​
Secrets Warning

If MCP server configs contain potential secrets, a warning is logged: 
Warning: MCP servers contain env vars that may include secrets: filesystem, remote-api.
   These will be written to mcp_config.json. Review before sharing the config file.
The converter looks for env var keys containing:
  • KEY
  • TOKEN
  • SECRET
  • PASSWORD
  • API

​
Name Normalization

Names are normalized to kebab-case:
InputOutput
workflows:planworkflows-plan
Plan Reviewplan-review
my/commandmy-command
UPPERCASEuppercase
Rules:
  • Lowercase only
  • Must start with a letter
  • Colons, slashes, spaces → hyphens
  • Special characters removed
  • Multiple hyphens collapsed

​
Example Output

Input (Claude agent): 
{
  "name": "plan-specialist",
  "description": "Planning agent",
  "capabilities": ["Break down features"],
  "body": "You are a planning specialist."
}
Output (~/.codeium/windsurf/skills/plan-specialist/SKILL.md): 
---
name: plan-specialist
description: Planning agent
---

# plan-specialist

## Capabilities
- Break down features

You are a planning specialist.
Input (Claude command): 
{
  "name": "workflows:plan",
  "description": "Create plan",
  "argumentHint": "<feature description>",
  "body": "You plan features. Task repo-research-analyst(analyze)."
}
Output (~/.codeium/windsurf/global_workflows/workflows-plan.md): 
---
description: Create plan
---

# workflows-plan

> Arguments: <feature description>

You plan features. Use the @repo-research-analyst skill: analyze.

​
Limitations

  • 12K character limit: Workflow content over 12,000 characters may be truncated
  • No hooks support: Windsurf does not have a hooks equivalent
  • Namespace flattening: Commands lose namespace prefixes (workflows:plan → workflows-plan)
  • Secrets in config: MCP env vars are written to JSON (review before sharing)
If your plugin has hooks, they will not be converted. Windsurf has no hooks equivalent.

​
Global vs Workspace

Install to ~/.codeium/windsurf/ (default):
bunx @every-env/compound-plugin install compound-engineering --to windsurf
  • Available in all Windsurf sessions
  • Workflows in global_workflows/
  • Skills and MCP config shared globally

​
Sync Support

Sync personal Claude config to Windsurf: 
bunx @every-env/compound-plugin sync --target windsurf
This syncs:
  • Personal skills from ~/.claude/skills/ (symlinked)
  • Personal commands from ~/.claude/commands/ (as workflows)
  • MCP servers from ~/.claude/settings.json (merged into mcp_config.json)

​
See Also

Windsurf Documentation

Official Windsurf documentation

Sync Command

Sync personal Claude config to Windsurf