> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/agent-skills/installation.md). # Installation CARTO Agent Skills are distributed from the public repo at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills). There are two ways to add them, depending on your agent. * **Install from the repository.** Claude Code, Claude.ai, Claude Desktop, Codex, Gemini CLI and the Skills CLI install the whole catalog from the repo and keep it up to date. * **Upload skill ZIPs.** Gemini Enterprise and Microsoft Copilot Studio take skills through an upload form, one skill at a time. Snowflake and Databricks load skills their own way. See [Snowflake CoWork](/carto-for-agents/connect-your-platform/snowflake-cowork.md), [Snowflake CoCo](/carto-for-agents/connect-your-platform/snowflake-coco.md) and [Databricks](/carto-for-agents/connect-your-platform/databricks.md). ## Prerequisites Before installing the skills, you need: * A [**CARTO account**](https://carto.com/signup) with workspace access. * An AI agent that can load skills. See the instructions for each agent below. Many skills route through the [CARTO MCP Server](/carto-for-agents/mcp-server.md), which needs no local install. [Connect it](/carto-for-agents/connect-your-platform.md) so its tools are available to your agent, including creating and editing maps and Workflows. Skills that script, run headless, do bulk and cross-organization work, or handle deeper administration and auditing (such as querying usage logs) use the [**CARTO CLI**](/carto-for-agents/cli.md). Install and authenticate it when you need those. ```bash npm install -g @carto/carto-cli carto auth login carto auth status # confirm: ✓ Authenticated ``` The `carto-basics` skill walks first-time users through CLI install, login, and profile setup. ## Install from the repository ### Claude Code Install via the Claude Code plugin marketplace: ``` /plugin marketplace add CartoDB/agent-skills /plugin install carto-skills@carto-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, so there's nothing else to invoke. ### Claude.ai and Claude Desktop Claude.ai and Claude Desktop install the same plugin as Claude Code. Open **Customize > Plugins**, click **+** in **Personal plugins**, select **Add marketplace > Add from a repository**, and enter `CartoDB/agent-skills`. Then install **carto-skills**. See [Claude](/carto-for-agents/connect-your-platform/claude.md#add-the-carto-agent-skills) for the full steps, including how organization admins share it. If you can't use plugins, [upload the skill ZIPs](#upload-skill-zips) instead. ### 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. See [Codex](/carto-for-agents/connect-your-platform/codex.md) for the full setup. ### 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 with `/carto:`, for example `/carto:carto-basics`. ### Skills CLI ```bash npx skills add CartoDB/agent-skills ``` The Skills CLI reads `skills/catalog.json` from the repo and registers each skill independently. Use it when you want to install a subset. ### Other agents Any agent that can load a skill, plugin, or rules file from a repo can use the same skills. Point it at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills) and its `skills/catalog.json`. ## Upload skill ZIPs Some agents take skills through an upload form, one skill at a time, as a **ZIP file with `SKILL.md` at the archive root**. You don't need to clone or zip anything, since every skill is published as a ready-made ZIP that always reflects the current version. ``` https://github.com/CartoDB/agent-skills/releases/latest/download/.zip ``` The **Download** column of the [Skills catalog](/carto-for-agents/agent-skills/skills-catalog.md) has the link for each skill. ### Gemini Enterprise Open **Skills**, click **Upload skill**, and drop the ZIP. Gemini reads the skill name and description from `SKILL.md` and turns the skill on. See [Google Gemini Enterprise](/carto-for-agents/connect-your-platform/google-gemini-enterprise.md#add-the-carto-agent-skills) for how an administrator enables skills first. ### Microsoft Copilot Studio Open your agent on the **Build** tab, click **+** next to **Skills**, choose **Upload a skill**, and drop the ZIP. See [Microsoft Copilot Studio](/carto-for-agents/connect-your-platform/microsoft-copilot-studio.md#add-the-carto-agent-skills). ### Claude without plugins Go to **Settings > Capabilities > Skills**, click **Upload skill**, and choose the ZIP. {% hint style="info" %} Skills are layered. A use-case skill relies on `carto-create-workflow`, which relies on the utility skills. Upload forms don't follow those references, so upload the dependencies too, starting with the four utility skills. See [Dependencies and routing](/carto-for-agents/agent-skills/skills-catalog.md#dependencies-and-routing). {% endhint %} ## Upgrading Skills ship continuously from upstream `master`. The catalog version is tracked in [`skills/catalog.json`](https://github.com/CartoDB/agent-skills/blob/master/skills/catalog.json) at the repo root. * **Installed from the repository.** Refresh or reinstall through your agent to pull the latest catalog. * **Uploaded as ZIPs.** Uploaded skills don't update themselves. Download the ZIP again from the [Skills catalog](/carto-for-agents/agent-skills/skills-catalog.md) and upload it. The agent asks whether to replace the existing skill of the same name. ## 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 CARTO on your behalf through the MCP Server or the CLI, whichever fits the request. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.carto.com/carto-for-agents/agent-skills/installation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.