# Installation

CARTO Agent Skills are distributed from the public repo at [`CartoDB/agent-skills`](https://github.com/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**](https://carto.com/signup) with workspace access.
* **Node.js 18+** and the [**CARTO CLI**](/carto-for-agents/cli.md) installed and authenticated:

  ```bash
  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

```bash
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`](https://github.com/CartoDB/agent-skills/blob/master/.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`](https://github.com/CartoDB/agent-skills/blob/master/gemini-extension.json), with one command per skill under [`commands/carto/`](https://github.com/CartoDB/agent-skills/tree/master/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`](https://github.com/CartoDB/agent-skills/blob/master/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/carto-for-agents/agent-skills/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.