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 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 is authoritative on the current list.

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.

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 and it is MIT licensed. For Claude Code you can skip the installer and symlink the directory into a project by hand:

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 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 for the current list and what each module covers
• MCP server for the sixteen tools and per-client setup
• Our MCP server, sixteen tools deep for what the tools actually do
• Maps for AI agents, with no human in the loop for the discovery, keys and payment surface underneath all of this

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