# Agent skills

The [MCP server](/docs/mcp) gives an AI agent **live tools**: it can call
`route`, `check_adr_tunnel`, `geocode` and the rest against a real deployment.
Agent skills are the other half: **know-how, not tools.** They are small
Markdown knowledge modules that teach a coding agent *how to build with*
MapMap (the truck/ADR routing gotchas, how `@mapmap/maps` wants to be wired,
how to move an app off Mapbox) so it writes correct code on the first try
instead of guessing.

Skills and tools compose: install the MCP server so the agent can *act*, and
the skills so it *acts well*. Skills carry no credentials and make no network
calls; they are read by the agent as context.

**Status:** live. The skills install today from
[`Mapmapai/mapmap-agent-skills`](https://github.com/Mapmapai/mapmap-agent-skills)
(MIT). Ten skills ship now; the set grows as the platform does.

## Install

```sh
npx skills add Mapmapai/mapmap-agent-skills            # all skills
npx skills add Mapmapai/mapmap-agent-skills --list     # see what's inside
npx skills add Mapmapai/mapmap-agent-skills --skill mapmap-truck-adr-routing
```

This works across Claude Code, Cursor, Codex, VS Code with Copilot and other
agents that read `SKILL.md` modules. For Claude Code you can also install by
hand, per project:

```sh
git clone https://github.com/Mapmapai/mapmap-agent-skills.git
cd your-project
mkdir -p .claude && ln -s ../mapmap-agent-skills/skills .claude/skills
```

## The skills

| Skill | Teaches | Reach for it when |
|---|---|---|
| `mapmap-mcp-setup` | Connecting any MCP client to MapMap | wiring an agent to the server |
| `mapmap-truck-adr-routing` | Truck routing with dimensional limits and ADR tunnel codes | routing commercial or dangerous-goods vehicles |
| `mapmap-web-maps-integration` | `@mapmap/maps`: maps, routing, turn-by-turn | building a web map or navigation UI |
| `mapmap-map-design` | Designing branded map styles from a reference | "make our maps look like airbnb.com" |
| `mapmap-fleet-optimisation` | Multi-vehicle VRP with truck/ADR constraints | planning fleet routes and deliveries |
| `mapmap-offline-territories` | Signed offline packages, key pinning, OTA | shipping offline maps in a mobile app |
| `mapmap-migrate-from-mapbox` | Porting a Mapbox app to MapMap | moving off Mapbox GL / Directions |
| `mapmap-migrate-from-google-maps` | Porting a Google Maps Platform app | moving off Routes / Distance Matrix / Maps JS |
| `mapmap-x402-payments` | How agents pay per call | budgeting or automating API spend |
| `mapmap-self-host-ops` | Running the whole stack yourself | standing up the Docker distro |

### `mapmap-mcp-setup`

Connect any MCP client to MapMap and call the tools correctly. Covers the
hosted endpoint (`https://mcp.mapmap.ai/mcp`), copy-paste config for Claude
Code, Claude Desktop, Cursor, Codex, VS Code, Windsurf and the Claude API MCP
connector, the full tool reference with the `{lat, lon}` / metres / seconds
conventions, how to read a tool error and self-correct, and the self-host env
vars (`VALHALLA_URL`, `PHOTON_URL`, `VROOM_URL`, `STUDIO_URL`) plus the
DNS-rebinding and unauthenticated-endpoint caveats. Start here; it is the
knowledge counterpart to the [MCP guide](/docs/mcp).

### `mapmap-truck-adr-routing`

MapMap's differentiator, made safe to code against. Covers both request shapes
(the OSRM-compatible `GET /route/v1/truck/…` and the native `POST /route` with
a top-level `adr` object), the rules that prevent the common `400`s (truck
parameters require the `truck` profile, bare coordinates are `lon,lat`, slashed
tunnel codes must be URL-encoded, and contradicting your own
`costing_options.truck` is a `costing-conflict`), the worst-case ADR semantics
and the full tunnel-restriction-code table, `check_adr_tunnel` for a decision
without routing, and the premium pricing class (one truck/ADR call draws 20
included calls). See [conventions](/docs/conventions) for the canonical ADR
reference this skill distils.

### `mapmap-web-maps-integration`

Build a web map and turn-by-turn UI with `@mapmap/maps` without hitting the
usual walls. Covers the two gotchas that render a map silently blank (the
container needs an explicit height; import MapLibre's stylesheet), map creation
with a truck route drawn live, guidance banners and voice (and why de-duping
spoken instructions is the caller's job), the `NavigationCamera` chase cam
(unsupported under the globe projection; switch to mercator), applying a
Studio theme's navigation design from `extra.nav`, and the non-negotiables:
structural OpenStreetMap attribution and why 3D buildings stay off in native
navigation views. Pairs with [SDKs](/docs/sdks) and [maps](/docs/maps).

### `mapmap-map-design`

The design judgement the style tools don't carry. The MCP's
`list_style_layers` / `create_style` / `set_palette` / `set_layer_paint` give
an agent the *mechanics* of styling; this skill teaches it to use them with
taste. Covers the theme document and the 19 palette slots as an instrument,
a brand-to-palette method (pick the base from the brand's background,
desaturate brand colours for surfaces, spend the accent in one place,
usually the route line, not the base map), label-legibility rules
(`textPrimary` ≥ 4.5:1 against `background`, halo ≈ background), matching a
bundled fontstack to the brand's type, restrained layer overrides, and the
publish/iterate flow with the `422` self-correction loop. Includes a worked
"make maps like airbnb.com" theme: calm warm-neutral base, coral spent only
on the route and navigation UI via `extra.nav`. Pairs with
[maps, tiles & Studio](/docs/maps).

### `mapmap-fleet-optimisation`

Multi-vehicle, multi-stop planning on `POST /optimise`, modelled correctly.
Covers vehicles versus jobs versus shipments (pickup–delivery pairs that must
ride the same vehicle, pickup first), time windows, capacities and skills,
why the gateway computes the travel-time matrix with its own engine so a
truck/ADR profile shapes the whole plan, a complete worked request and
response, and the errors that break plans: `adr` requires costing `truck`,
requesting geometry is a `400` (fetch legs via `POST /route`), and the
200-location fair-use cap with strategies for splitting bigger problems. An
optimisation bills a flat 10 calls. Via MCP the same capability is the
`optimise_routes` tool. Distils [route optimisation](/docs/optimisation).

### `mapmap-offline-territories`

Ship offline maps with the trust model intact. Covers what a signed territory
package is (ed25519 + BLAKE3, content-addressed layers), pinning the 64-hex
verifying key at build time (never fetched over the same channel as the
packages it validates), verify-then-promote installs that leave no trace on
failure, the differential OTA update flow, the monthly download allowance and
its `402` body, `TerritoryStore` on Android (Kotlin) and iOS (Swift), and
self-host key generation (`snfactory keygen`) versus hosted key distribution.
Distils [territories](/docs/territories) and the mobile half of
[SDKs](/docs/sdks).

### `mapmap-x402-payments`

The payment decision tree an agent must implement. Covers dispatching `402`
(a way to pay) versus the two `429`s (stop or wait), the x402 wire body and
the honest status (unconfigured deployments are "x402-ready" with an empty
`accepts` array, where an `X-PAYMENT` retry is ignored and prepaid credit is
the rail that works everywhere), plus the free balance-polling endpoint, the
4xx refund rule that makes spend budgetable, and why minting extra keys never
dodges quota. Distils [machine payments](/docs/x402).

### `mapmap-migrate-from-mapbox`

Move a Mapbox GL JS / Directions API app across with a URL and token swap for
most of it. Covers `pk.…` tokens becoming self-served `snk_` keys, an
endpoint-mapping table (Directions → `route`, Matrix → `matrix`, Isochrone,
Map Matching → `trace_route`, Geocoding → `geocode`, Optimized Trips →
`optimise`, Styles, Tiles), the Mapbox GL JS → MapLibre GL JS drop-in, what to
do with custom Mapbox styles, the honest list of what MapMap does *not* offer
(server-side raster images, global POI search, day-one worldwide tile
coverage), the two-class billing model, and swapping the Mapbox wordmark for
the required OpenStreetMap credit.

### `mapmap-migrate-from-google-maps`

The bigger sibling of the Mapbox migration. Covers the key/billing swap
(Google API key + billing account → one-call card-free `snk_` key), the
endpoint mapping (Routes/Directions → `/route`, `computeRouteMatrix` →
`/matrix`, Geocoding → `/geocode`, Maps JavaScript API → MapLibre GL with a
MapMap style URL), the `lat,lng` → `lon,lat` coordinate-order gotcha, and an
honest not-portable list: Places richness (reviews, photos, opening hours),
Street View and traffic-aware routing have no MapMap replacement, and hosted
coverage is territory-based today. What you gain: truck/ADR routing Google
does not offer, self-hosting, and cost predictability.

### `mapmap-self-host-ops`

Run the gateway, routing engine, geocoder and MCP server yourself from one
Docker Compose file. Covers first boot from a Geofabrik extract (and why the
gateway sits in `Created` while tiles build), issuing operator keys via
`/admin/keys`, the `geocoding` and `mcp` compose profiles, the env switches
that turn features on (`SN_VROOM_URL`, `SN_PHOTON_URL`, `SN_TILES_DIR`,
`SN_ROUTING_ENGINE`, `SN_CORS_ORIGINS`, `SN_TRUST_PROXY`), and the production
notes: TLS at the proxy, the ed25519 verifying-key trust anchor, backing up the
`gateway_data` volume, and the procurement pack. Distils
[self-hosting](/docs/self-host).

## How skills and tools work together

A worked example: you ask your agent to "add a hazmat truck route to my Next.js
app."

1. `mapmap-mcp-setup` and `mapmap-web-maps-integration` are already in the
   agent's context, so it knows the coordinate convention and that the map
   container needs a height.
2. `mapmap-truck-adr-routing` tells it that the `truck` options only apply to
   the `truck` profile and that `tunnel_code: "D"` implies `hazmat`, so the
   generated call is valid first time.
3. The MCP `route` tool (or the SDK) executes it against a live deployment.

The skills are also just Markdown you can read yourself; they double as a
concise field guide for the same tasks. Every doc page here is served as raw
Markdown too: append `.md` to any URL.

## Closing the loop

Skills are only as good as the friction they know about, so **all ten skills
end with the same optional final step**: once the integration works (or the
agent stops trying) it offers to send one structured retro back with the MCP
`submit_integration_retro` tool (or `POST /v1/feedback` directly). What it
built, the problems by area, the gotchas, the wins and the docs gaps it hit.
Those reports are what the next revision of these skills is written from.

The step is consent-gated in the skill text itself: the agent submits only if
**you** have approved sending feedback to MapMap, and if you have not said
yes it asks once, then skips. Only the structured schema fields travel:
never your conversation, code or credentials. Declining costs you nothing and
the rest of the skill is unaffected.

The tool is documented on the [MCP page](/docs/mcp), the endpoint behind it in
the [API reference](/docs/api-reference#integration-feedback), and the terms
(exact fields, 24-month retention, no model training, deletion on request) in
the [Agent Feedback Programme](/legal/agent-feedback).

## Next steps

- [MCP server](/docs/mcp): the live tools these skills teach agents to use
- [For AI agents](/agents): the discovery, keys and machine-payment surface
- [Quickstart](/docs/quickstart): issue a key and route a truck in two calls
- [Truck & ADR conventions](/docs/conventions): the canonical reference behind the routing skill