skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
cartodb/agent-skills59 installs

carto-preview-builder-map

Preview an existing saved CARTO Builder map inline in the chat via the CARTO MCP server — resolve the map with read_maps (by name or search), then render it with view_map by map ID. Use whenever the user references a saved Builder map — by URL, by ID, or by name. Renders a lightweight read-only preview (layers, basemap, viewport, popups, legend). Widgets, SQL parameters, map description, and other Builder-only features are NOT included; the user can click "Open in Builder" for the full experience. Triggers on "show me the X map", "open the Y map", "preview the Z map", and inline previews of a freshly-created map. Distinct from carto-create-builder-maps (authoring), carto-render-inline-map (ad-hoc deck.gl spec), and carto-develop-app (developer app).

How do I install this agent skill?

npx skills add https://github.com/cartodb/agent-skills --skill carto-preview-builder-map
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is safe. It provides legitimate instructions for interacting with the CARTO platform's map rendering and resolution tools. No malicious patterns, obfuscation, or unauthorized data access were found.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

carto-preview-builder-map

Renders a lightweight inline preview of an existing saved CARTO Builder map via the CARTO MCP server. The user references the map (by URL, ID, or name); the agent resolves it with read_maps and loads it inline with view_map.

Tool contract. This skill consumes the read_maps and view_map tools exposed by the CARTO MCP server. The tools' input shapes and access-control rules (the user must own, be shared on, or have public access to the map) are documented in the tools' own MCP descriptions — read them via the MCP host's tool-inspector or by calling tools/list. This skill stays focused on routing, name → ID resolution, and setting expectations on the lightweight preview; it does NOT duplicate the tools' specs.

This skill is MCP-only — there's no CLI equivalent for inline rendering — and needs an MCP-Apps host (Claude.ai, Claude Desktop, ChatGPT). Detection signals and host support: carto-basics/references/access-paths.md.

Step 1 — detect what's available

Both view_map and read_maps must be in your tool list, and the host must render MCP Apps. Token vs OAuth: on a token MCP session view_map is offered but read_maps is not — loading by explicit URL/ID still works; name-based search needs an OAuth session (or ask the user for the map URL).

SetupWhat to do
Tools present + host rendersProceed normally.
Tools present + host doesn't render (Gemini CLI, Codex CLI, MCP Inspector, MCPJam — text-only)Tell the user the host can't render maps inline; suggest opening the Builder URL directly.
view_map not presentThe MCP server isn't attached. Tell the user; don't try to reconstruct the saved map from scratch.

Resolution rules (URL / ID / name)

User inputWhat to do
Builder URL https://<workspace>.app.carto.com/builder/<mapId>Extract <mapId> from the URL; pass it to view_map directly.
Bare UUIDPass it to view_map directly.
Name / topic ("the retail-stores map", "my last week's accidents analysis")Search with read_maps first (by the topic hint), then load by ID. See match handling below.

For name-based lookup, restrict to the user's own maps if they said "my map". Default sort is updated_at desc — most recently edited first.

Match handling (after read_maps)

ResultAction
1 matchLoad it via view_map with the matched ID. Confirm to the user which map you're loading by name.
>1 matchesList names + dates + thumbnails. Ask the user to pick. Don't guess.
0 matchesTell the user no saved map matches. Offer carto-render-inline-map (an ad-hoc view_map spec) as an alternative for the same data.

Set expectations on the preview (always)

The preview is lightweight:

  • ✓ Layers, basemap, viewport, popups, legend — exactly as configured in Builder, including stroke styles (dashed / dotted lines and polygon borders).
  • ✗ Widgets, SQL parameters, map description, AI agent configuration, and other Builder-only features are NOT included.

After loading, tell the user: "Loaded [name] as a lightweight preview. Widgets, SQL parameters, and the map description aren't included — click 'Open in Builder' in the rendered widget for the full experience." Set this expectation BEFORE the user asks why the preview looks different from the live Builder map.

Post-creation preview workflow

After a map is created via carto-create-builder-maps (create_map over MCP, or carto maps create on the CLI), pass the returned mapId to view_map to preview inline — the fastest edit → save → preview loop for styling iterations. Still the lightweight preview: debugging widgets or SQL parameters needs the full Builder.

When to pick a different skill

  • Ad-hoc visualization, no saved map exists → carto-render-inline-map (an ad-hoc view_map spec).
  • Authoring / editing a permanent map → carto-create-builder-maps (create_map / update_map over MCP, or the carto maps CLI).
  • Building a from-scratch deck.gl app → carto-develop-app.

Anti-patterns to avoid

  • Reconstructing a saved map from a hand-built deck.gl spec instead of loading it by ID. If the user references an existing map, ALWAYS resolve via read_maps and load the saved map first. Re-rendering loses fidelity (saved layers, popups, legend) AND it's slower.
  • Skipping read_maps when the user references a map by name. Don't guess the ID. Search first.
  • Promising widgets, SQL parameters, or map description in the preview. They're not rendered. Set expectations upfront.
  • Picking the most-recent match silently when read_maps returns multiple. Surface the choices and let the user pick.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/cartodb/agent-skills/carto-preview-builder-map">View carto-preview-builder-map on skillZs</a>