Agent Skills
mapbox agent-skills installs the
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.
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 listmapbox agent-skills installmapbox agent-skills updatemapbox agent-skills uninstall
Where skills go
All four commands share the destination flags; list, install, and
update also take --ref:
| 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. Can't be combined with --agent or --global. |
--ref <REF> | Branch, tag, or commit to install from. Defaults to main; a commit hash pins the install. |
The CLI supports fifteen agents:
| Agent | --agent | This project | Home |
|---|---|---|---|
| Claude Code | claude-code | .claude/skills | ~/.claude/skills |
| Codex | codex | .agents/skills | ~/.codex/skills |
| Amp | amp | .agents/skills | $XDG_CONFIG_HOME/agents/skills |
| Cline | cline | .agents/skills | ~/.agents/skills |
| Continue | continue | .continue/skills | ~/.continue/skills |
| Cursor | cursor | .agents/skills | ~/.cursor/skills |
| Gemini CLI | gemini-cli | .agents/skills | ~/.gemini/skills |
| GitHub Copilot | github-copilot | .agents/skills | ~/.copilot/skills |
| Goose | goose | .goose/skills | $XDG_CONFIG_HOME/goose/skills |
| Kiro CLI | kiro-cli | .kiro/skills | ~/.kiro/skills |
| OpenCode | opencode | .agents/skills | $XDG_CONFIG_HOME/opencode/skills |
| Qwen Code | qwen-code | .qwen/skills | ~/.qwen/skills |
| Roo Code | roo | .roo/skills | ~/.roo/skills |
| Windsurf | windsurf | .windsurf/skills | ~/.codeium/windsurf/skills |
| Zed | zed | .agents/skills | ~/.agents/skills |
An agent counts as installed when its home directory exists.
CLAUDE_CONFIG_DIR and CODEX_HOME move those two agents' directories,
and $XDG_CONFIG_HOME falls back to ~/.config on every platform. Naming
more than one agent that shares a directory still writes it once. For an
agent not in the table, use --dir.
With no --agent, --global, or --dir, and no agent detected,
install, update, and uninstall fail with no_agent_detected rather
than writing nowhere. list still reports what's published.
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:
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. An unknown name is an error that suggests the nearest published one. |
--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:
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:
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 holds no SKILL.md, so 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:
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