Agent skills

The MCP server 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 (MIT). Ten skills ship now; the set grows as the platform does.

Install

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:

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

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.

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 400s (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 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 and 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.

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.

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 and the mobile half of SDKs.

mapmap-x402-payments

The payment decision tree an agent must implement. Covers dispatching 402 (a way to pay) versus the two 429s (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.

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.

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, the endpoint behind it in the API reference, and the terms (exact fields, 24-month retention, no model training, deletion on request) in the Agent Feedback Programme.

Next steps

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