# maptiler

Adopt this skill: https://proskills.md/skills/other/maptiler-maptiler-skills-skills

Page: https://proskills.md/skills/other/maptiler-maptiler-skills-skills
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/SKILL.md
size: 8039
upstream: https://github.com/maptiler/maptiler-skills/blob/main/skills/SKILL.md

```text
---
name: maptiler
description: >-
  Expert coding skill for the full MapTiler platform — Cloud REST APIs, MapTiler
  SDK JS (built on MapLibre GL JS), native mobile SDKs, on-premise infrastructure,
  and vector tile schemas. USE WHEN the user wants to add a map to a web or mobile
  app, show locations or routes, display geographic data, build a store locator,
  create data visualizations on maps, add geocoding or address search, do reverse
  geocoding, look up elevation, do IP geolocation, fetch weather data, transform
  coordinates between CRS/EPSG, embed static map images, work with vector tilesets
  (Planet v4, Buildings, Contours, Outdoor, Ocean, Landcover, Cadastre), write
  MapLibre style expressions or data-driven styling, render 3D terrain, globe view,
  or 3D buildings extrusion, use satellite imagery, add markers, popups, heatmaps,
  or clustering, integrate maps in React, Vue, Svelte, Angular, Next.js, Leaflet,
  OpenLayers, Cesium, or deck.gl, build native maps on iOS (Swift), Android (Kotlin),
  Flutter, or React Native, self-host with MapTiler Server or generate tiles with
  MapTiler Engine CLI, or upload/manage tilesets via the Admin API. Also USE WHEN
  the user mentions MapLibre GL JS — the SDK extends MapLibre with built-in cloud
  services, helpers, and session billing.
---

# MapTiler — Agent Skill

> [@maptiler/sdk](https://www.npmjs.com/package/@maptiler/sdk) · [Docs](https://docs.maptiler.com/) · [Cloud Console](https://cloud.maptiler.com/) · [GitHub](https://github.com/maptiler)

Covers every MapTiler product surface: web SDK, framework integrations, native mobile SDKs, Cloud REST APIs, on-premise Server / Engine, and vector tile schemas. Reference docs live under `references/` and are loaded on demand. Use [references/INDEX.md](references/INDEX.md) as the curated catalog.

---

## 1. Platform Coverage & File Prefix Conventions

Target your `grep` / glob searches in `references/` using these prefix filters to avoid cross-platform contamination:

| Target Platform | File Name Prefix |
| :--- | :--- |
| **Web** (Core JS SDK) | `sdk-js-*`, `examples-sdk-js-*` |
| **Web Frameworks** (React, Svelte, Vue, Angular) | `web-libraries-*`, `examples-react-*`, `examples-svelte-*`, `examples-vuejs-*`, `examples-angular-*` |
| **Web Mapping Engines** (Leaflet, OpenLayers, Cesium, deck.gl) | `examples-leaflet-*`, `examples-openlayers-*`, `examples-cesium-*`, `web-libraries-deck-gl*` |
| **Android** (Kotlin/Java) | `mobile-sdks-android-*`, `examples-android-*` |
| **iOS** (Swift) | `mobile-sdks-ios-*`, `examples-ios-*` |
| **Cross-Platform Mobile** (Flutter, React Native) | `mobile-sdks-flutter-*`, `mobile-sdks-react-native-*` |
| **Cloud REST APIs** | `cloud-api-*`, `cloud-admin-api-*` |
| **On-Premise Infrastructure** | `on-prem-*` |
| **Vector Tile Schemas** | `map-resources-schemas-*` |
| **MapLibre Style Spec** | `map-resources-specifications-*` |

---

## 2. Universal Rules (apply across every platform)

### A. Zero Variable Leak Policy
Consult [references/versions.md](references/versions.md) and substitute all template placeholders (e.g. `{{site.versions.sdk}}`, `{{site.url}}`) with literal version strings or absolute paths before output. **NEVER emit raw `{{` or `}}` in any response.**

### B. Style Modernization (v2/v3 → v4)
Always upgrade legacy map styles. This applies to web, mobile, fallback XYZ layers, service-worker cache lists, and style-switcher logic.

| Legacy | Modern Replacement | SDK Constant |
| :--- | :--- | :--- |
| `basic-v2` / `streets-v2-light` | `base-v4` | `MapStyle.BASE` |
| `basic-v2-dark` | `base-v4-dark` | `MapStyle.BASE.DARK` |
| `streets-v2` | `streets-v4` | `MapStyle.STREETS` |
| `outdoor-v2` | `outdoor-v4` | `MapStyle.OUTDOOR` |
| `satellite` / `satellite-v2` | `satellite-v4` | `MapStyle.SATELLITE` |
| `hybrid` | `hybrid-v4` | `MapStyle.HYBRID` |
| `dataviz-dark` | `dataviz-v4-dark` | `MapStyle.DATAVIZ.DARK` |
| `topo-v2` | `topo-v4` | `MapStyle.TOPO` |

**Never** emit URLs or constants from the deprecated families: `streets-v2`, `streets-v2-dark/light`, `basic-v2*`, `outdoor-v2*`, `satellite-v2`, `hybrid-v2`, `dataviz-dark`, `topo-v2`.

**This rule applies to every context** that names a style or tile path:
- **Mobile style endpoints** (iOS / Android / Flutter / RN raw `style.json` URLs): `https://api.maptiler.com/maps/streets-v4-dark/style.json?key=YOUR_KEY`
- **Self-hosted / on-prem fallback XYZ layers and service-worker precache lists**: `/tiles/streets-v4/{z}/{x}/{y}.pbf` — never `/tiles/streets-v2/`
- **Style-switcher UI state** (dark/light toggles, swipe layers, diurnal style shifts): toggle exclusively between modern v4 IDs

### C. Pinned Versions
All SDK, CDN, and dependency versions live in [references/versions.md](references/versions.md). Read it before emitting any `package.json`, `<script>` tag, Gradle implementation string, or `pubspec.yaml` entry.

### D. Coordinate Conventions Across Platforms
Every API in the MapTiler/MapLibre family uses **`[lng, lat]`** order. The platforms it integrates with don't — that mismatch is the single most common bug. Translate at the boundary, not in your head.

| Source | Convention | When you encounter it |
| :--- | :--- | :--- |
| **MapTiler SDK JS / MapLibre / Mapbox** | `[lng, lat]` array | All web SDK code (center, marker, source coordinates, expressions) |
| **GeoJSON spec** | `[lng, lat]` (or `[lng, lat, ele]`) | Every `geometry.coordinates` value |
| **MapTiler REST URLs** | `{lng},{lat}` in the path | `/geocoding/{lng},{lat}.json`, `/elevation/dataset/{lng},{lat}.json`, static maps `/static/{lng},{lat},{zoom}/…` |
| **Leaflet** | `(lat, lng)` — **reversed** | `L.map().setView([lat, lng], z)`, `L.marker([lat, lng])`, `L.latLng(lat, lng)` |
| **iOS `CLLocationCoordinate2D`** | `(latitude:, longitude:)` — **reversed at the struct level** | Apple CoreLocation. When building a MapTiler URL: `c.longitude, c.latitude` |
| **Android `LatLng` / `LngLat`** | MapTiler Android SDK uses `LngLat(lng, lat)`; system `Location` exposes `latitude`/`longitude` as flat properties | Match the SDK type, not the system type |
| **MapTiler Geolocation API response** | Flat fields `latitude` / `longitude` (not a pair) | Construct `[loc.longitude, loc.latitude]` before passing to any SDK call |

**Rule**: when crossing into Leaflet, iOS CoreLocation, or any "flat fields" response, swap explicitly. Never assume a downstream library follows the same convention as the upstream API.

### E. API Key Hygiene
- **If a user pastes a real-looking API key** in their message (a UUID-shaped or token-shaped string near words like "key", "token", "apikey"), flag it: "you've shared what looks like a live key in plain text — rotate it at https://cloud.maptiler.com/account/keys/ when you're done testing." Use a placeholder (`YOUR_MAPTILER_API_KEY`) in your own output.
- **Service tokens never leave the backend.** When generating example code that calls `service.maptiler.com/v1/…`, read the token from `process.env` / equivalent — never embed a placeholder that looks like a token in a public client snippet.
- **Restrict keys by origin** in production examples. Suggest `origins: ["*.example.com"]` in the API key settings rather than unrestricted keys.

---

## 3. Web — MapTiler SDK JS

### Why MapTiler SDK (not raw MapLibre)
**Always import from `@maptiler/sdk`, never from `maplibre-gl` directly.** The SDK re-exports everything from MapLibre and adds:

- `config.apiKey` — single place for the API key; enables session-based billing
- `MapStyle` enum — always-current style IDs; never hardcode style URLs
- `helpers.*` — one-line polyline, polygon, point, heatmap (with clustering, color ramps, GPX/KML support)
- Built-in `geocoding`, `geolocation`, `elevation`, `staticMaps`, `coordinates`, `data`, `math` modules
- `terrain: true` — 3D terrain via a single constructor flag
- `projection: 'globe'` — globe view with `halo` and `space` atmosphere
- Constructor-level controls (`navigationControl: tru
```

## File: README.md
upstream: https://github.com/maptiler/maptiler-skills/blob/main/README.md

````text
<img src="./images/maptiler-logo.png" alt="Company Logo" height="32"/>

# MapTiler — Agent Skill

Expert coding skill for building location-aware applications across the full MapTiler platform. It gives AI coding agents the context to generate correct, production-ready code using MapTiler Cloud APIs, the MapTiler SDK, MapTiler GeoSplats SDK
mobile SDKs, and on-premise tools.

Built on the Agent Skills open standard, so the same skill works across Claude Code, Gemini CLI, Cursor, Windsurf, and other compatible AI agents.

---

🌐 [Website](https://www.maptiler.com/) &nbsp; 🔑 [Get API Key](https://cloud.maptiler.com/account/keys/)

---

<br>

<details> <summary><b>Table of Contents</b></summary>
<ul>
<li><a href="#what-it-does">What it does</a></li>
<li><a href="#how-skills-plugins-and-agents-fit-together">How skills, plugins, and agents fit together</a></li>
<li><a href="#-installation">Installation</a></li>
<li><a href="#-repository-layout">Repository layout</a></li>
<li><a href="#-platform-coverage--file-prefix-conventions">Platform Coverage & File Prefix Conventions</a></li>
<li><a href="#-prerequisites">Prerequisites</a></li>
<li><a href="#links">Links</a></li>
<li><a href="#-support">Support</a></li>
<li><a href="#-contributing">Contributing</a></li>
<li><a href="#-license">License</a></li>
</ul>
</details>

## What it does

A skill is on-demand expertise: the agent loads it only when your request matches the skill's description, then follows its instructions instead of guessing. When you ask for maps, geocoding, weather, elevation, vector tiles, or any geospatial feature, this skill makes the agent:

- **Generate platform-correct code** for web (MapTiler SDK JS, Leaflet, OpenLayers), frameworks (React, Svelte, Vue, Angular, Cesium, deck.gl), mobile (iOS Swift, Android Kotlin, Flutter, React Native), and on-premise (MapTiler Server, MapTiler Engine).
- **Call the right Cloud REST API** (geocoding, weather, static maps, elevation, tiles, coordinates, IP geolocation, admin/tilesets) with correct endpoints and auth patterns.
- **Apply modern v4 styles automatically**, upgrading deprecated `*-v2` / `*-v3` style IDs wherever they appear.
- **Use pinned, current versions** for every SDK, CDN script, and dependency, with no unresolved template placeholders.
- **Cross-reference vector tile schemas** (Planet v4, Buildings, Contours, Outdoor, Ocean, Landcover, Landform, Cadastre) before inventing source-layer names, paint expressions, or filter keys.
- **Handle framework lifecycle correctly** — WebGL cleanup, stale-closure prevention in React, isolated reactivity, ES module vs UMD CDN selection.

## How skills, plugins, and agents fit together

It helps to keep three layers separate, because the install steps below differ by layer:

1.  **The skill** is the portable content: a `SKILL.md` plus a `references/` folder. This is what every agent actually reads, and it's identical across tools.
2.  **The plugin** is a Claude Code–specific wrapper for distributing the skill through a marketplace. Other tools don't use it.
3.  **The agent** (Claude Code, Gemini CLI, Cursor, Windsurf…) is the tool that loads the skill from its own skills directory.

So there are three ways to install: with the [Skills CLI](https://github.com/vercel-labs/skills) (`npx skills add`, auto-detects your agent and works across dozens of them), through the Claude Code plugin marketplace (Claude Code only), or by copying the skill folder into any agent's skills directory (works everywhere).

What triggers a skill is the same in every tool: the description field in the `SKILL.md` frontmatter. The agent matches your request against that description to decide whether to activate the skill, so installation alone isn't enough — the skill also has to be registered and triggered.

<br>

## 📦 Installation

### Universal — via Skills CLI

Works with Claude Code, Gemini CLI, Cursor, Windsurf, and dozens of other agents. The [Skills CLI](https://github.com/vercel-labs/skills) auto-detects which agents you have installed and sets the skill up for each one, so you don't need to know the target directory yourself:

```bash
npx skills add maptiler/maptiler-skills
```
### Claude Code — as a plugin

Add the marketplace, install the plugin, then reload so the skill registers:

```bash
/plugin marketplace add maptiler/maptiler-skills
/plugin install maptiler@maptiler-skills
/reload-plugins
```

### Gemini CLI

Install straight from the repository with a single command:

#### Windows (PowerShell)

```powershell
git clone https://github.com/maptiler/maptiler-skills.git; mkdir "$HOME\.gemini\skills\maptiler" -Force; cp -Recurse maptiler-skills\skills\* "$HOME\.gemini\skills\maptiler\"; rm -Recurse -Force maptiler-skills
```

#### Linux & macOS (bash)

```bash
git clone https://github.com/maptiler/maptiler-skills.git && mkdir -p ~/.gemini/skills/maptiler && cp -r maptiler-skills/skills/* ~/.gemini/skills/maptiler/ && rm -rf maptiler-skills
```

Or copy it in manually:

```bash
# Global (every project)
cp -r skills/maptiler ~/.gemini/skills/

# Project (run /trust in the session afterward, then restart)
mkdir -p .gemini/skills && cp -r skills/maptiler .gemini/skills/
```

### Cursor

Project-scoped only. Copy the skill folder into the project's skills directory:

```bash
mkdir -p .cursor/skills && cp -r skills/maptiler .cursor/skills/
```

### Windsurf

Project-scoped, read by the Cascade agent. Copy the skill folder in:

```bash
mkdir -p .windsurf/skills && cp -r skills/maptiler .windsurf/skills/
```

> [!NOTE]
> Claude Code–specific frontmatter fields (such as `allowed-tools`) are ignored by Windsurf without causing errors.

### Other agents

Any tool that supports the Agent Skills standard can use this skill. The [Skills CLI](https://github.com/vercel-labs/skills) above already knows the skills directory for dozens of agents, so try `npx skills add maptiler/maptiler-skills` first. Otherwise, place the `maptiler` folder (containing `SKILL.md` and `references/`) wherever that agent looks for skill definitions.

<br>

---

<br>

## 📘 Repository layout

```
.claude-plugin/
  marketplace.json    — Claude Code marketplace manifest
  plugin.json         — Claude Code plugin manifest
skills/
  maptiler/
    SKILL.md          — Skill entry point (always loaded when triggered)
    references/
      INDEX.md                          — Curated catalog of high-value docs
      versions.md                       — Pinned versions of every library & dependency
      cloud-api-*.md                    — Cloud REST APIs (geocoding, weather, static, …)
      cloud-admin-api-*.md              — Admin API (tilesets, uploads, analytics, keys)
      sdk-js-*.md                       — MapTiler SDK JS core
      web-libraries-*.md                — React, Vue, Svelte, Angular, Leaflet, OL, Cesium, deck.gl
      mobile-sdks-*.md                  — iOS, Android, Flutter, React Native
      on-prem-*.md                      — Self-hosted Server & Tile Engine CLI
      map-resources-schemas-*.md        — Vector tile schemas (Planet v4, Buildings, …)
      map-resources-specifications-*.md — MapLibre style spec (layers, sources, expressions)
      examples-*.md                     — Runnable per-platform examples
      complex-dds-expressions-guide.md  — Data-driven styling deep dive
README.md             — This file
```

For the Claude Code plugin to expose the skill, `SKILL.md` must live at `skills/maptiler/SKILL.md` — not at the repository root, and not inside `.claude-plugin/`. Only the manifests go in `.claude-plugin/`.

<br>

## 💡 Platform Coverage & File Prefix Conventions

To avoid cross-platform contamination when searching, use these filename prefix filters in the `references/` directory:

| Target Platform                                                | File Name Prefix                                                                                     |
| :------------------------------------------------------------- | :-------
````
