Make SerpApi a master router skill

[shrey258]

Summary

Turn the SerpApi foundational skill into a master router so agents reliably pick the right engine/fields and can use the Chorus proxy without requiring user-managed keys.

Key Changes

• Rewrite Foundational/serpapi as a master router with an explicit decision table (engine/params/fields).
• Update SerpApi wrapper to use the Chorus proxy base URL and send x-api-key when VIBECODE_API_KEY is present.
• Clarify engine reference notes (Amazon params, trends shape, Google Play nesting).

Testing

• Manual: run bash scripts/serpapi.sh google_hotels --q "hotels near JFK" --check_in_date 2026-06-12 --check_out_date 2026-06-13 --max_price 200 --currency USD --gl us inside a runner container and verify JSON returns.

Note

Make SerpApi script a master router skill with proxy support

• Rewrites SKILL.md to define a routing contract, decision table, and high-value workflow patterns (hotels, Reddit research, price comparison, job search, venue reviews) across SerpApi engines.
• Updates serpapi.sh to default api_key to chorus-proxy when SERPAPI_API_KEY is unset, targeting the Chorus proxy at ${SERPAPI_BASE_URL:-https://serpapi.com.proxy.chorus.com}/search.json.
• Adds conditional forwarding of VIBECODE_API_KEY as an x-api-key header when the variable is set.
• Expands engines.md with Amazon engine coverage and clarifies response key fields for Google Trends, Apple App Store, and Google Play.
• Behavioral Change: the script no longer exits when SERPAPI_API_KEY is unset; real credentials should not be embedded and are replaced by the proxy key mechanism.

^{Macroscope summarized ef02221.}

---

Note

Medium Risk
Proxy and optional API-key behavior change how requests authenticate; misconfiguration outside Chorus runners could break calls, but scope is limited to skill docs and the wrapper script.

Overview
This PR reframes the SerpApi foundational skill as a master router: agents classify intent via a decision table (engine, parameters, and response keys), follow workflow guides for hotels, forum research, shopping, jobs, and maps/reviews, and apply response discipline instead of assuming generic organic_results.

scripts/serpapi.sh now targets the Chorus proxy (SERPAPI_BASE_URL defaulting to https://serpapi.com.proxy.chorus.com/search.json), uses a chorus-proxy placeholder when SERPAPI_API_KEY is unset, and sends x-api-key when VIBECODE_API_KEY is set. Skill metadata no longer requires SERPAPI_API_KEY in the environment.

references/engines.md aligns setup docs with the proxy, adds an Amazon engine section, and clarifies Trends, App Store, and Google Play response shapes. The inline engine catalog table was removed from SKILL.md in favor of the router table and engines.md.

^{Reviewed by Cursor Bugbot for commit ef02221. Bugbot is set up for automated code reviews on this repo. Configure here.}

Greptile Summary

Reframes the SerpApi foundational skill as a master router by replacing the flat engine catalog with an intent-to-engine decision table, high-value workflow guides, and explicit response-field contracts. The shell wrapper switches from hard-failing on a missing key to a chorus-proxy placeholder and routes requests through the Chorus proxy by default, with optional x-api-key injection from VIBECODE_API_KEY.

• SKILL.md: New routing contract, decision table covering 12 intent categories, and five concrete workflow sections (hotels, Reddit opinions, price comparison, jobs, venue reviews). SERPAPI_API_KEY is removed as a required env var.
• scripts/serpapi.sh: BASE_URL defaults to the Chorus proxy; VIBECODE_API_KEY, when set, is forwarded as x-api-key to whichever URL BASE_URL resolves to.
• references/engines.md: Proxy URL updated, Amazon engine section added, and response-field notes added for Apple App Store and Google Play.

Confidence Score: 5/5

Safe to merge — changes are limited to documentation and a thin wrapper update with intentional proxy defaults.

The executable change in serpapi.sh is small and well-scoped: a default fallback key, a new base URL, and a conditional header. The x-api-key forwarding concern only manifests when SERPAPI_BASE_URL is deliberately overridden to a non-Chorus host while VIBECODE_API_KEY is also present — an atypical configuration. No application data paths, auth logic, or stored state are affected.

No files require special attention beyond the minor credential-forwarding note on serpapi.sh.

Important Files Changed

Filename	Overview
Foundational/serpapi/SKILL.md	Rewrites the skill as a master router: adds routing contract, decision table mapping user intents to engines/params/fields, and high-value workflow guides. Removes the SERPAPI_API_KEY env requirement from metadata. Documentation-only change with no logic.
Foundational/serpapi/references/engines.md	Updates proxy URL reference, adds Amazon engine section, and adds response-field notes for Apple App Store and Google Play. Pure documentation addition; no executable logic changed.
Foundational/serpapi/scripts/serpapi.sh	Changes API_KEY fallback from hard-fail to chorus-proxy placeholder, switches default BASE_URL to the Chorus proxy, and conditionally injects x-api-key header from VIBECODE_API_KEY. The header is forwarded unconditionally to any BASE_URL rather than being scoped to the Chorus proxy, and the curl if/else branch is redundant.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant Script as serpapi.sh
    participant Proxy as Chorus Proxy
    participant SerpApi

    Agent->>Script: bash serpapi.sh engine [--param value]
    Note over Script: Resolve auth key and base URL from env
    Script->>Script: build_url with engine and params

    alt proxy auth header present
        Script->>Proxy: GET /search.json + x-api-key header
    else no proxy auth
        Script->>Proxy: GET /search.json
    end

    Proxy->>SerpApi: Proxied request
    SerpApi-->>Proxy: JSON response
    Proxy-->>Script: JSON response
    Script-->>Agent: Formatted JSON output

Loading

Comments Outside Diff (1)

1. Foundational/serpapi/scripts/serpapi.sh, line 36-37 (link)

   Amazon engine missing from script header comment

   The Amazon engine section was added to engines.md in this PR but the list of supported engines in the header comment of serpapi.sh was not updated. Agents and developers reading the inline help will not see amazon as a supported engine, which undermines the discoverability goal of the master-router skill.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: Foundational/serpapi/scripts/serpapi.sh
   Line: 36-37
   
   Comment:
   **Amazon engine missing from script header comment**
   
   The `Amazon` engine section was added to `engines.md` in this PR but the list of supported engines in the header comment of `serpapi.sh` was not updated. Agents and developers reading the inline help will not see `amazon` as a supported engine, which undermines the discoverability goal of the master-router skill.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
Foundational/serpapi/scripts/serpapi.sh:165-169
The `if/else` branching on `${#CURL_HEADERS[@]}` is redundant. In Bash, `"${array[@]}"` on an empty declared array expands to nothing, so the two `curl` invocations are identical when `CURL_HEADERS` is empty. A single call handles both cases cleanly.

```suggestion
http_code=$(curl "${CURL_HEADERS[@]}" -sw '%{http_code}' -o "$tmpfile" "$url")
```

### Issue 2 of 2
Foundational/serpapi/scripts/serpapi.sh:161-163
**`VIBECODE_API_KEY` forwarded to any `BASE_URL`, not only the Chorus proxy**

The `x-api-key` header is added whenever `VIBECODE_API_KEY` is non-empty, regardless of where `BASE_URL` points. If a developer or CI environment sets `SERPAPI_BASE_URL` to direct `serpapi.com` (or another third-party proxy) while `VIBECODE_API_KEY` is also set, the Vibecode credential is sent to that external host and will appear in its access logs. Adding a guard that only injects the header when the resolved base URL matches the Chorus proxy domain would prevent unintended credential forwarding.

_{Reviews (6): Last reviewed commit: "drop platform-recommender references in ..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3257959. Configure here.}