# Agent Skills

`mapbox agent-skills` installs the [Mapbox Agent Skills](https://github.com/mapbox/mapbox-agent-skills): hand-written guidance for coding agents on cartography, token security, style quality, geospatial operations, and the mobile and web SDKs. Twenty skills, each a directory of Markdown.

This is **not** the same as [`generate-skills`](https://docs.mapbox.com/cli/reference/generate-skills/). `generate-skills` writes a skill describing this CLI's own commands. `agent-skills` installs skills about building with Mapbox in general. They share the same destination flags and nothing else.

Neither command needs an access token — the skills repository is public. `/plugin marketplace add mapbox/mapbox-agent-skills` and `npx skills add mapbox/mapbox-agent-skills` install the same content; this command exists for environments where npm isn't available, and so people who install the CLI discover the skills exist at all.

-   [`mapbox agent-skills list`](#mapbox-agent-skills-list)
-   [`mapbox agent-skills install`](#mapbox-agent-skills-install)
-   [`mapbox agent-skills update`](#mapbox-agent-skills-update)
-   [`mapbox agent-skills uninstall`](#mapbox-agent-skills-uninstall)

## Where skills go

`list`, `install`, and `update` share these flags:

| Parameter | Description |
| --- | --- |
| `--agent <AGENT>` | Which coding agent to target, repeatable. Defaults to whichever agents are installed. |
| `--global` | Write to the agent's home directory, for every project, instead of this one. |
| `--dir <DIR>` | Write here and nowhere else. |
| `--ref <REF>` | Branch, tag, or commit to install from. Defaults to `main`. |

An agent counts as installed when its home directory exists. Most agents write to `.agents/skills` in the current project (or an agent-specific home directory such as `~/.agents/skills`); Claude Code is the exception, using `.claude/skills`. Naming more than one agent that shares a directory still writes it once.

## `mapbox agent-skills list`

The published skills, with a short description, and a marker on the ones already installed at the destinations you're checking.

**Examples:**

```sh
mapbox agent-skills list
mapbox agent-skills list --agent claude-code
mapbox agent-skills list --ref v1.0.0
```

## `mapbox agent-skills install`

Installs skills into every destination that applies. With no name given, installs all twenty.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<name>` | Skill to install, repeatable. Defaults to all. |
| `--force` | Replace a skill directory that's already there. |
| `--dry-run` | List the files this would write, then exit without writing them. |

An existing skill directory stops the install — the command reports every conflict before writing anything, so it never silently merges or overwrites a directory. `--force` replaces it.

**Examples:**

```sh
mapbox agent-skills install
mapbox agent-skills install mapbox-cartography mapbox-token-security
mapbox agent-skills install --agent claude-code --global
```

## `mapbox agent-skills update`

Re-installs the skills already present and reports what changed. With no name given, updates every skill installed at the destinations you're checking. It never installs a skill that isn't already there — that's `install`'s job.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<name>` | Skill to update, repeatable. Defaults to every skill already installed. |
| `--dry-run` | Report what would change, then exit without changing it. |

Installed files are compared with the published ones byte for byte, so a local edit gets restored along with anything upstream changed. Because it can't tell a local edit from an upstream one, it asks before replacing anything at a terminal; `--yes`/`MAPBOX_YES` answers in advance.

**Examples:**

```sh
mapbox agent-skills update
mapbox agent-skills update mapbox-cartography
mapbox agent-skills update --dry-run
```

## `mapbox agent-skills uninstall`

Removes installed skill directories. At least one name is required.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<name>` | Skill to remove, repeatable. Required. |
| `--force` | Remove a directory even though it doesn't look like an installed skill. |
| `--dry-run` | List what this would remove, then exit without removing it. |

This is the only `agent-skills` command that makes no network request — it works from what's on disk, so it can remove a skill that's since been unpublished. At a terminal it asks before deleting; `--yes`/`MAPBOX_YES` answers in advance.

**Examples:**

```sh
mapbox agent-skills uninstall mapbox-cartography
mapbox agent-skills uninstall mapbox-cartography mapbox-token-security
mapbox agent-skills uninstall mapbox-cartography --global --agent claude-code
```