Surf

Surf - VibeSurf Browser Automation

Overview

Control real browsers through VibeSurf. This skill delegates to specialized sub-skills.

> 🚨 VIBESURF STATUS (Auto-detected at session start) > > Check the ` status at the TOP of this context: > - ✅ **Status: running** → Proceed with surf skills > - ❌ **Status: not_running** → Ask user to run vibesurf (NEVER run it yourself) > > **Check manually:** curl $VIBESURF_ENDPOINT/health` (default: http://127.0.0.1:9335)

How to Call VibeSurf API

VibeSurf exposes three core HTTP endpoints. All requests go to the configured endpoint (check the status line above for the actual endpoint):

1. List Available Actions

GET $VIBESURF_ENDPOINT/api/tool/search?keyword={optional_keyword}

Returns all available VibeSurf actions.

2. Get Action Parameters

GET $VIBESURF_ENDPOINT/api/tool/{action_name}/params

Returns JSON schema for the action's parameters.

3. Execute Action

POST $VIBESURF_ENDPOINT/api/tool/execute
Content-Type: application/json

{
  "action_name": "action_name_here",
  "parameters": {
    // action-specific parameters
  }
}

Workflow:

1. Search for action → Get action name
2. Get params schema → See required/optional parameters
3. Execute → Call with parameters

> ⚠️ CRITICAL: Parameter Error Handling > > ALWAYS call GET /api/tool/{action_name}/params before executing ANY action if you are unsure about parameters. > > When you encounter a parameter error: > 1. STOP - Do not guess or make up parameters > 2. CALL GET /api/tool/{action_name}/params to get the exact schema > 3. READ the response to identify required vs optional parameters > 4. RETRY with correct parameters > > Never blindly retry with incorrect parameters. Always fetch the schema first!

Which Skill to Use

| Task Type | Use Skill | Action Name | |-----------|-----------|-------------| | AI web search | search | skill_search | | Fetch URL content as markdown | fetch | skill_fetch | | Extract lists/tables | js_code | skill_code | | Extract page content | crawl | skill_crawl | | Summarize page | summary | skill_summary | | Stock/financial data | finance | skill_finance | | Trending news | trend | skill_trend | | Screenshot | screenshot | skill_screenshot | | Precise browser control | browser | browser.* actions | | Task-oriented automation (sub-agent) | browser-use | execute_browser_use_agent | | Social Media Platform APIs | website-api | get_website_api_params, call_website_api | | Pre-built workflows | workflows | search_workflows, execute_workflow | | Gmail/GitHub/Slack | integrations | get_all_toolkit_types, execute_extra_tool | | LLM profile settings | config-llm | config/llm-profiles/* | | MCP server config | config-mcp | config/mcp-profiles/* | | VibeSurf key/workflows | config-vibesurf | vibesurf/verify-key, vibesurf/import-workflow | | Composio key/toolkits | config-composio | composio/verify-key, composio/toolkits | | Schedule workflows | config-schedule | schedule/* | | File upload/download | file | /api/files/* | | Voice/ASR configuration | config-voice | /api/voices/* |

Configuration Skills

Use these skills to configure VibeSurf settings:

| Config Task | Skill | When to Use | |-------------|-------|-------------| | Add/switch LLM | config-llm | Manage AI model profiles (OpenAI, Anthropic, etc.) | | Add MCP server | config-mcp | Configure MCP integrations for extended tools | | VibeSurf API key | config-vibesurf | Set up API key, import/export workflows | | Enable Gmail/GitHub/etc | config-composio | Configure Composio toolkits and OAuth | | Schedule workflows | config-schedule | Set up cron-based workflow automation | | Voice/ASR profiles | config-voice | Configure speech recognition profiles |

Note: After configuring Composio or MCP tools, use them through the integrations skill (see tool naming: cpo.{toolkit}.{action} or mcp.{server}.{action}).

Decision Flow

Browser/Web Task
│
├─ Need to search for information/bug/issue? → search (skill_search) [PREFERRED]
│  Examples: "Search for solutions to [bug name]", "Find latest info about [topic]"
│  Fallback: If skill_search doesn't find complete info → browser.search + browser.click + extract/summary/crawl
│
├─ Need to fetch URL content directly? → fetch (skill_fetch)
│  Examples: "Fetch content from [URL]", "Get documentation at [URL]", "Read this webpage"
│  Use for: Getting structured markdown from any URL without browser interaction
│
├─ Need to open website? → browser (browser.navigate)
│  Examples: "Open documentation site", "Go to [URL]", "Check this page"
│
├─ Need to extract data?
│  ├─ Lists/tables/repeated items? → js_code (skill_code)
│  Examples: "Extract all product prices", "Get all post titles"
│  └─ Main content? → crawl (skill_crawl)
│  Examples: "Get the article content", "Extract main section"
│
├─ Need summary? → summary (skill_summary)
│  Examples: "Summarize this page", "What's this about?"
│
├─ Stock/finance data? → finance (skill_finance)
│  Examples: "Stock price for AAPL", "Financial data for [company]"
│
├─ Trending news? → trend (skill_trend)
│  Examples: "What's trending", "Hot topics"
│
├─ Screenshot? → screenshot (skill_screenshot)
│  Examples: "Take a screenshot", "Show me the page"
│
├─ Need precise control or step-by-step operations? → browser (browser.*)
│  Examples: "Click the button", "Type in the field", "Scroll down", "Navigate then click"
│  Use for: Any browser task where you want explicit control over each action
│
├─ Debug/test website or monitor logs? → browser (debugging actions)
│  Examples: "Monitor console logs", "Capture network traffic", "Debug this page"
│  Workflow: start_console_logging/start_network_logging → perform actions → stop_*_logging
│  Use cases: Website testing, frontend/backend debugging, reverse engineering
│
├─ Complex task-oriented automation? → browser-use (execute_browser_use_agent)
│  Examples: "Fill out this form", "Extract data from multiple pages", "Login and check dashboard"
│  Use for: Complex tasks where describing the goal is easier than specifying steps
│  Fallback: If browser-use fails → use browser with get_browser_state loop
│
├─ Platform API (XiaoHongShu/Youtube/etc)? → website-api
│  Examples: "Get XiaoHongShu posts", "Call Weibo API"
│
├─ External app (Gmail/Google Calendar/GitHub)? → integrations
│  Examples: "Send email via Gmail", "Create GitHub PR", "Post to Slack"
│
└─ Pre-built workflow? → workflows
│  Examples: "Run video download workflow", "Execute auto-login workflow"
│
├─ Need to configure LLM/MCP/VibeSurf/Composio/Voice? → config-* skills
│  Examples: "Add OpenAI API key", "Enable Gmail toolkit", "Import workflow"
│  - LLM profiles → config-llm
│  - MCP servers → config-mcp
│  - VibeSurf key/workflows → config-vibesurf
│  - Composio key/toolkits → config-composio
│  - Schedule workflows → config-schedule
│  - Voice/ASR profiles → config-voice

Quick Reference

| Goal | Skill | Action | |------|-------|--------| | Search web | search | skill_search | | Fetch URL content | fetch | skill_fetch | | Extract prices/products | js_code | skill_code | | Get main content | crawl | skill_crawl | | Summarize page | summary | skill_summary | | Stock data | finance | skill_finance | | Hot topics | trend | skill_trend | | Take screenshot | screenshot | skill_screenshot | | Click/navigate/type | browser | browser.click, browser.navigate, etc. | | Task-oriented automation | browser-use | execute_browser_use_agent (fallback to browser if fails) | | Social Media Platform APIs | website-api | call_website_api | | Send email | integrations | execute_extra_tool | | Run workflow | workflows | execute_workflow | | Configure LLM profiles | config-llm | config/llm-profiles/* | | Configure MCP servers | config-mcp | config/mcp-profiles/* | | Configure VibeSurf key | config-vibesurf | vibesurf/verify-key | | Enable Composio toolkits | config-composio | composio/toolkits | | Schedule workflows | config-schedule | schedule/* | | Upload/Download files | file | /api/files/* | | Configure Voice/ASR | config-voice | /api/voices/* |

Common Patterns

| Request | Use Skill | Action | |---------|-----------|--------| | "Search for X" | search | skill_search (preferred) | | "Search for bug/issue" | search first, fallback to browser | skill_search, then browser.search + extract if needed | | "Fetch content from [URL]" | fetch | skill_fetch | | "Get documentation at [URL]" | fetch | skill_fetch | | "Read this webpage" | fetch | skill_fetch | | "Extract all prices" | js_code | skill_code | | "Summarize this page" | summary | skill_summary | | "Stock info for AAPL" | finance | skill_finance | | "What's trending" | trend | skill_trend | | "Take a screenshot" | screenshot | skill_screenshot | | "Navigate and click" | browser | browser.navigate, browser.click | | "Fill out this form" | browser-use or browser | execute_browser_use_agent (or manual browser operations) | | "Get XiaoHongShu posts" | website-api | call_website_api | | "Get Youtube video content or transcript" | website-api | call_website_api | | "Send Gmail" | integrations | execute_extra_tool | | "Run video download" | workflows | execute_workflow | | "Debug console logs" | browser | browser.start_console_logging → actions → browser.stop_console_logging | | "Monitor network traffic" | browser | browser.start_network_logging → actions → browser.stop_network_logging | | "Test this website" | browser | Use console/network logging actions | | "Configure LLM" | config-llm | config/llm-profiles endpoints | | "Add MCP server" | config-mcp | config/mcp-profiles endpoints | | "Set VibeSurf API key" | config-vibesurf | vibesurf/verify-key | | "Import workflow" | config-vibesurf | vibesurf/import-workflow | | "Enable Gmail/GitHub" | config-composio | composio/toolkits + toggle endpoints | | "Schedule workflow" | config-schedule | schedule/* endpoints | | "Upload file" / "Download file" | file | /api/files/* endpoints | | "Configure voice profile" / "ASR" | config-voice | /api/voices/* | | "Speech to text" / "Transcribe audio" | config-voice | /api/voices/asr |

Error Handling

| Error | Solution | |-------|----------| | VibeSurf not running | Check status in context (SessionStart hook already detected)If not_running: Inform user to run vibesurfNEVER run the command yourself | | Don't know which skill | Read skill descriptions above | | Action not found | Call GET /api/tool/search to list all actions | | Wrong parameters | Call GET /api/tool/{action_name}/params to see schema | | browser-use fails or gets stuck | Fallback to browser: use get_browser_state → browser.{action} → repeat loop | | LLM/Crawl/Summary errors | Cause: No LLM profile configuredSolution: Use config-llm to add an LLM profile first | | Integration tools empty/not found | Cause: Composio/MCP not configuredSolution: Use config-composio or config-mcp to enable toolkits first |

VibeSurf Status (Auto-Detected at Session Start)

🔍 LOOK FOR THE STATUS IN THE CONTEXT ABOVE - DO NOT IGNORE IT

The status appears at the very top:

**VibeSurf Integration** - Status: running/not_running

Actions based on status:

• Status: running → VibeSurf is ready, use surf actions directly
• Status: not_running → Inform user to start VibeSurf, DO NOT run commands to start it yourself

To manually re-check status (only if needed):

curl $VIBESURF_ENDPOINT/health
# Returns HTTP 200 if running, connection error if not running
# Default endpoint: http://127.0.0.1:9335 (if VIBESURF_ENDPOINT is not set)

Getting Browser State

> 🔍 Check Current Browser State > > When user asks about current page content or browser status (e.g., "What's on the current page?", "What tabs are open?", "What's the browser showing?"), use the get_browser_state action to get the current browser state including: > - All open tabs and their URLs > - Active tab information > - Page content/state > - Highlighted Screenshot > > Action: get_browser_state > > This is essential when you don't have context about what the user is currently viewing in their browser.

browser vs browser-use

Both skills can accomplish the same browser tasks - they're complementary tools:

| Approach | Best For | How It Works | |----------|----------|--------------| | browser-use | Complex, long tasks | Task-oriented sub-agent: describe goal + desired output, agent figures out steps | | browser | Precise control | Step-by-step manual control: explicit actions with full visibility | | Hybrid | Best reliability | Try browser-use first, fallback to browser if it fails |

Fallback pattern when browser-use fails:

browser-use fails or gets stuck
→ get_browser_state (inspect page)
→ browser.{action} (perform action)
→ get_browser_state (verify & plan next)
→ repeat until complete

Key principle: Choose based on task complexity and control needs, not step count. Browser-use is not exclusive to multi-step tasks; browser can handle complex workflows too.

---

API Parameter Troubleshooting

If you encounter API parameter errors when calling VibeSurf endpoints, you can visit the interactive API documentation at:

http://127.0.0.1:9335/docs

For example: http://127.0.0.1:9335/docs#/config/create_mcp_profile_api_config_mcp_profiles_post

> Note: This is a fallback approach. In most cases, reading the corresponding skill documentation (e.g., config-mcp skill) should provide sufficient guidance on how to use the API correctly. Only refer to the /docs endpoint when the skill documentation doesn't resolve your issue or you need to inspect specific request/response schemas.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vibesurf-ai
• Source: vibesurf-ai/claude-surf
• License: MIT

Install and usage instructions live in the source repository linked above.