Installation

CARTO Agent Skills are distributed from the public repo at CartoDB/agent-skills. Each supported AI harness installs them differently, but they all read the same upstream catalog.

Prerequisites

Before installing the skills, every harness needs:

• A CARTO account with workspace access.

• Node.js 18+ and the CARTO CLI installed and authenticated:

  npm install -g @carto/carto-cli
  carto auth login
  carto auth status      # confirm: ✓ Authenticated

• One of the four supported AI agent harnesses (below).

The carto-basics skill walks first-time users through CLI install, login, and profile setup.

Claude Code

Install via the Claude Code plugin marketplace:

/plugin marketplace add CartoDB/agent-skills
/plugin install carto-skills@agent-skills

All skills ship together as a single bundle (carto-skills). Once installed, Claude Code routes to individual skills automatically based on the user's request — there's nothing additional to invoke.

Skills CLI

npx skills add CartoDB/agent-skills

The Skills CLI reads skills/catalog.json from the repo and registers each skill independently. Useful when you want to install a subset.

Codex

The Codex plugin manifest is at .codex-plugin/plugin.json in the repo. Install it with your Codex client's extension command (refer to your Codex version's docs for the exact verb).

Gemini CLI

The Gemini extension manifest is at gemini-extension.json, with one command per skill under commands/carto/. After install, invoke a skill via /carto:<skill-name> — for example /carto:carto-basics.

Upgrading

Skills ship continuously from upstream master. Re-install or refresh through your harness to pull the latest catalog. The catalog version is tracked in skills/catalog.json at the repo root.

Verify the install

Once installed, ask your agent something CARTO-specific that maps to a skill — for example:

"List my CARTO maps."

"Connect to my BigQuery warehouse called analytics and show me the available tables."

"Run a hotspot analysis on the crashes_2024 table."

If the skills are installed correctly, the agent will route to the appropriate skill (carto-basics, carto-explore-datawarehouse, carto-hotspot-analysis, …), follow the skill's playbook, and drive the CARTO CLI on your behalf.