# CARTO Agent Skills

**CARTO Agent Skills** is a public catalog of short, on-demand playbooks that teach AI coding tools (Claude Code, Skills CLI, Codex, Gemini CLI) how to drive the CARTO platform fluently. The repository is at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills) on GitHub.

## Why agent skills?

Generic LLMs know *about* CARTO but make small mistakes when actually driving it: wrong CLI flags, outdated SQL dialects, missing async-job handling, the wrong import shape for a tileset. Each skill in the catalog is a focused playbook the agent loads on demand when a user's request matches the skill's domain, so the agent ships idiomatic, working CARTO output the first time.

Skills run **locally** inside your AI agent. When a skill is triggered, the agent reads the skill's instructions and uses the [CARTO CLI](/carto-for-agents/cli.md) on your machine to act on your behalf. It authenticates with your local CARTO profile and operates against the warehouses you've already connected. No data leaves your environment via the skills repository. Everything flows through the CARTO CLI you control.

## Three tiers

The catalog is organized in three layered tiers. An agent routes to the right skill automatically based on user intent.

* **Utility**. Foundational CARTO primitives (install, auth, query, explore). Loaded by other skills as a shared base.
* **Platform**. CARTO product surfaces (workflows, builder maps, imports, data observatory, org admin). Build on the utility tier.
* **Use-case patterns**. Recipe skills that compose platform skills into end-to-end spatial analyses (hotspot analysis, site selection, trade areas, GWR). Each carries trigger keywords so the agent routes on user intent.

For the full catalog with descriptions and trigger keywords, see [Skills catalog](/carto-for-agents/agent-skills/skills-catalog.md). For the layering rationale, see [`ARCHITECTURE.md`](https://github.com/CartoDB/agent-skills/blob/main/ARCHITECTURE.md) in the repo.

## Supported AI clients

Skills ship to four AI agent harnesses, all from the same upstream catalog:

* **Claude Code**. Installed as a marketplace plugin (`carto-skills@agent-skills`).
* **Skills CLI**. Installed via `npx skills add CartoDB/agent-skills`.
* **Codex**. Installed via the Codex plugin manifest at `.codex-plugin/plugin.json`.
* **Gemini CLI**. Installed via the Gemini extension manifest, exposing each skill as a `/carto:<skill-name>` slash command.

For step-by-step install instructions per harness, see [Installation](/carto-for-agents/agent-skills/installation.md).

## How it composes with the rest of CARTO for Agents

* The skills **drive the** [**CARTO CLI**](/carto-for-agents/cli.md) on your machine. The CLI is a hard prerequisite. Install and authenticate it before installing the skills bundle.
* The skills are independent of the [CARTO MCP Server](/carto-for-agents/mcp-server.md). The MCP Server is for web and desktop AI clients. The skills are for AI coding tools that work locally with the CLI; today there are install paths for Claude Code, Skills CLI, Codex, and Gemini CLI.
* As you publish workflows as MCP tools, the same workflows are usable through the MCP server. The skills focus on the CLI surface area.

## Source of truth

This documentation summarizes the catalog as it ships today. The canonical, always-up-to-date source is the public repo at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills), specifically `skills/catalog.json`, which lists every shipped skill, its tier, its dependencies, and its description.


---

# 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.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.