# Skills are what an agent knows, tools are what it does

> **Note, updated 2 August 2026.** The MCP server exposed sixteen tools when this was written. It exposes **32** today. The argument is unchanged and the skills named below are all still shipped. See [/docs/mcp](/docs/mcp) for the current tool list.

`npx skills add Mapmapai/mapmap-agent-skills` installs ten Markdown knowledge modules that teach a coding agent how to build with MapMap, from MCP wiring, truck and ADR routing and `@mapmap/maps` integration to fleet optimisation, offline territories, Mapbox and Google Maps migration, machine payments and running the self-host distro. They are the counterpart to our MCP server, not a replacement for it. The MCP server gives an agent sixteen live tools it can call. The skills give it the knowledge to call them correctly. An agent holding a `route` tool and nothing else can reach the endpoint and still not know that a `tunnel_code` belongs on the request, or that truck parameters are rejected on any profile except `truck`.

## Why does a tool without knowledge still produce wrong code?

Because a tool schema tells an agent what it *may* send, never what it *should* send. That gap is where the bugs live.

Take the `route` tool. Its schema lists the profile, the locations and the costing options. Every field is documented and typed. Nothing in it says that a 44-tonne tanker carrying petrol needs a `tunnel_code`, and nothing warns that leaving the field off returns a perfectly valid `200` with a route through a tunnel the vehicle may not legally enter. The call succeeds. The schema was obeyed. The code is still wrong, and you find out at the tunnel mouth.

`mapmap-truck-adr-routing` exists to close exactly that gap. It carries the rules that a schema cannot express:

- Truck parameters require the `truck` profile. Sending `height`, `weight`, `hazmat` or `tunnel_code` on `driving` or `bicycle` returns `400 InvalidValue`.
- Bare coordinate pairs are `lon,lat`, following the OSRM convention. JSON bodies use named `{"lat": …, "lon": …}` fields and never positional ones.
- Slashed tunnel codes must be URL-encoded. `B/D` becomes `B%2FD`.
- Contradicting your own `costing_options.truck` from the `adr` object is rejected with `400 costing-conflict`, listing the offending fields. Set truck facts in one place.

None of that is discoverable from a tool definition. All of it is the difference between code that works first time and an afternoon of reading error bodies.

## What do the skills teach?

Each one covers a surface of the platform that agents routinely get wrong on the first attempt: MCP wiring, truck and ADR routing, web maps, map design, Mapbox migration and self-host operations. Ten ship today, the set grows as the platform does, and the [agent skills reference](/docs/skills) is authoritative on the current list.

| Skill | Teaches | Reach for it when |
|---|---|---|
| `mapmap-mcp-setup` | Connecting any MCP client to MapMap, the sixteen-tool reference, the `{lat, lon}` and metres and seconds conventions | wiring an agent to the server |
| `mapmap-truck-adr-routing` | Truck routing with dimensional limits and ADR tunnel codes, worst-case semantics, the tunnel-restriction table | routing commercial or dangerous-goods vehicles |
| `mapmap-web-maps-integration` | `@mapmap/maps` for maps, routing and turn-by-turn guidance | building a web map or navigation UI |
| `mapmap-map-design` | Brand to palette method across the 19 palette slots, label-legibility rules, the publish loop | making the map look like your product |
| `mapmap-migrate-from-mapbox` | Endpoint mapping, `pk.…` tokens becoming `snk_` keys, the Mapbox GL JS to MapLibre GL JS swap | moving off Mapbox |
| `mapmap-self-host-ops` | The Docker Compose distro, operator keys, the env switches, production notes | standing up the stack yourself |

The pattern repeats in each one. `mapmap-web-maps-integration` leads with the two things that render a map silently blank: the container needs an explicit height, and you have to import MapLibre's stylesheet. `mapmap-self-host-ops` explains why the gateway sits in `Created` on first boot while tiles build, which otherwise reads as a broken install. `mapmap-migrate-from-mapbox` carries an honest list of what we do not offer, including server-side raster images and global POI search, because an agent that discovers a gap halfway through a migration has already cost you the day.

## How do you install them?

One command, and it works across Claude Code, Cursor, Codex, VS Code with Copilot and other agents that read `SKILL.md` modules.

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

The repository is [`Mapmapai/mapmap-agent-skills`](https://github.com/Mapmapai/mapmap-agent-skills) and it is MIT licensed. For Claude Code you can skip the installer and symlink the directory into a project by hand:

```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
```

That is the whole install. There is no account step, because there is nothing to authenticate against.

## What happens when both are installed?

The agent writes the correct call before it makes any call at all. Ask it to "add a hazmat truck route to my Next.js app" with both layers present and the sequence runs like this:

1. `mapmap-web-maps-integration` is in context, so the generated map component has an explicit container height and the MapLibre stylesheet imported.
2. `mapmap-truck-adr-routing` is in context, so the request goes out on the `truck` profile with `tunnel_code: "D"` and `hazmat: true` set once, in one place.
3. The MCP `route` tool executes it against a live deployment.

Without step two, step three still runs. It returns a route. The route goes through the tunnel.

The economics matter here too, and the skills state them so the agent can reason about cost. Truck and ADR routing is the premium class at 1p per call, and one premium call draws 20 of your included calls, so the free tier's 50,000 monthly calls is 2,500 all-premium calls. An agent that knows this plans a demo differently from one that does not.

## What skills do not do

They are static Markdown, and every limitation follows from that.

- **They carry no credentials and make no network calls.** Installing skills does not get you a key. That is still `POST /v1/keys`, and it still returns a provisional `snk_` key good for 1,000 calls over 72 hours.
- **They are a snapshot.** A skill is pinned at install time and goes stale as the platform moves. Re-run `npx skills add` to refresh. We would rather say that plainly than pretend a text file stays current on its own.
- **They do not enforce anything.** An agent can read the tunnel-code table and ignore it. Skills raise the floor on first-try correctness. They are not a validator, and the gateway's `400` is still the thing that stops a bad request.
- **They only help agents that read `SKILL.md` modules.** If yours does not, the skills are just Markdown you can read yourself, which is a fair use of them but not the point.
- **The hosted MCP server they teach against is open for evaluation, not production.** No key to connect, fair use applies. `route`, `matrix`, `check_adr_tunnel`, `list_style_layers` and `get_style` work today. `geocode` and `optimise_routes` answer with tool errors until their upstreams are enabled on the hosted deployment, and style publishes are metered and may be unavailable. `mapmap-mcp-setup` says all of this too, because a skill that oversells the server it configures is worse than no skill.

## Try it

Install the skills, connect the [MCP server](/docs/mcp) and ask your agent for a hazmat truck route. If it writes a valid `tunnel_code` request without you mentioning ADR, the knowledge layer is doing its job.

- [Agent skills docs](/docs/skills) for the current list and what each module covers
- [MCP server](/docs/mcp) for the sixteen tools and per-client setup
- [Our MCP server, sixteen tools deep](/news/mcp-server) for what the tools actually do
- [Maps for AI agents, with no human in the loop](/news/maps-for-ai) for the discovery, keys and payment surface underneath all of this

Routing derives from OpenStreetMap, so credit "© OpenStreetMap contributors" when you render it.