Carto basics

Skill CartoDB/agent-skills/skills/carto-basics

Start here for first-time CARTO use — install the CLI, authenticate, switch profiles, understand JSON output and async job patterns. Also orients on the two parallel access paths into the CARTO platform (CLI for authoring/scripting, MCP server for inline interactions in chat hosts) and which skills cover each.From its SKILL.md

Install

npx -y skills add CartoDB/agent-skills --skill carto-basics

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.8 KB, as published. Nobody here has run it

carto-basics

CARTO is reachable through two parallel access paths, and most agent setups use one or both:

CARTO CLI (@carto/carto-cli) — the primary path for authoring, scripting, and headless contexts. Used by most other skills in this catalog.
CARTO MCP Server — a parallel path for inline interactions in chat-based agent hosts (Claude.ai, Claude Desktop, ChatGPT). Renders maps inline, exposes data discovery and saved-Builder-map preview tools, and dynamically registers the user's saved CARTO Workflows as MCP tools when available.

Use this skill before any other CARTO skill — it covers installation, authentication, profiles, the global CLI flags every other CARTO skill assumes, and how to detect / route between the two access paths.

When to use this skill

Setting up the CLI for the first time on a new machine.
The user reports authentication errors (auth status failures, expired tokens).
The user wants to switch between organizations or environments.
A downstream skill needs --profile, --json, --token, or --base-url and you don't yet know how those work.

Preflight — run before any CLI operation

Every CARTO skill assumes a working, authenticated carto CLI. Walk these checks before your first CLI call, and re-run them at the start of each task — ephemeral sandboxes (e.g. Claude Code Cowork tasks) wipe the CLI between tasks. An attached MCP server, by contrast, persists at the account level (see below).

CLI present? Run carto --version. If command not found, install it yourself — tell the user you're installing, then do it; never deflect with "run this on your own machine." The npm command plus the EACCES / writable-prefix fallback that sandboxes need are in references/installation.md.
Authenticated? Run carto auth status. If not, use the headless flow carto auth login --no-launch-browser — an agent can't complete a browser OAuth. Never open or wait on a browser, and never ask the user for an M2M / API token instead (references/authentication.md).

If install or auth can't complete, say so and stop — never silently fall back to Python / SQL / deck.gl or other non-CARTO tooling.

What's in this skill

Topic	Reference
Installing the CLI (npm, version verification)	references/installation.md
Authentication: browser, headless `--no-launch-browser`, API tokens, SSO	references/authentication.md
Profiles: managing multiple orgs / environments	references/profiles.md
Global flags: `--json`, `--debug`, `--yes`, `--token`, `--base-url`, `--profile`, env vars	references/global-options.md
Access paths: CLI vs MCP routing, detection, host support	references/access-paths.md

Access paths: CLI vs MCP server

The CLI and MCP server serve different intents — some flows chain across both. When an intent maps to MCP but the server isn't attached (or the host doesn't render MCP Apps), surface that; don't silently fall back to a hand-rolled map. The CLI is wiped per task in ephemeral sandboxes; an attached MCP server persists at the account level. Full routing table, detection signals, and host support: references/access-paths.md.

Always-on guidance

Never silently degrade. A CARTO request is answered with CARTO tooling. If the CLI can't be installed or authenticated (or a needed MCP route isn't attached), surface the blocker and stop — don't substitute Python, SQL, deck.gl, or other generic geospatial workarounds, and don't ask for an M2M token in place of carto auth login --no-launch-browser.
Always pass --json when you need machine-readable output. CLI text output is for humans and may change.
Map URLs use the tenant domain from auth status, not a generic workspace URL. Private maps live at https://{tenant_domain}/builder/{map_id}; public/shared maps at https://{tenant_domain}/map/{map_id}. Never construct workspace-{region}.app.carto.com URLs.
Confirmation prompts: destructive commands like maps delete prompt for the literal word "delete". Pass --yes (or --json) for non-interactive use.
Async jobs: imports create and sql job poll until completion by default. Pass --async (where supported) to return immediately and poll separately.