# maplibre-source-wiring

The maplibre-source-wiring skill diagnoses blank MapLibre GL JS maps, mismatched vector layers, and inactive feature state. Use it when a configured source draws nothing.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 408 installs · ★ 164 repo stars
- Author: maplibre
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/maplibre/maplibre-agent-skills/tree/HEAD/skills/maplibre-source-wiring/SKILL.md
- Updated: 2026-11-14
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/maplibre-source-wiring

## What it does

This skill connects a MapLibre GL JS source to a style and traces failures that leave the console quiet. It covers TileJSON through `url`, direct `tiles` templates, exact `source-layer` names, and layer placement such as drawing data beneath labels.

It also checks the identifiers used by `promoteId` and `setFeatureState`, plus missing icons, CORS, and glyph-related failures. A vector layer with the wrong `source-layer` name simply produces no pixels, so the tile schema is the first place to compare.

When there is no TileJSON endpoint, a hand-written `tiles` source needs metadata such as `minzoom` and `maxzoom`. Without that range, MapLibre assumes `maxzoom: 22` and can request empty zoom levels. The skill supports Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add maplibre/maplibre-agent-skills --skill maplibre-source-wiring -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/maplibre-source-wiring/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/maplibre-source-wiring/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add maplibre/maplibre-agent-skills --skill maplibre-source-wiring -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/maplibre-source-wiring/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add maplibre/maplibre-agent-skills --skill maplibre-source-wiring -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/maplibre-source-wiring/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install maplibre/maplibre-agent-skills skills/maplibre-source-wiring
```

2. **Manually: put the files in place**
- File: `.github/skills/maplibre-source-wiring/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add maplibre/maplibre-agent-skills --skill maplibre-source-wiring -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/maplibre/maplibre-agent-skills --path skills/maplibre-source-wiring
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/maplibre-source-wiring/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add maplibre/maplibre-agent-skills --skill maplibre-source-wiring -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/maplibre/maplibre-agent-skills/tree/HEAD/skills/maplibre-source-wiring/SKILL.md

## When to use it
- diagnose a blank layer with no console error
- match `source-layer` names to a vector tile schema
- choose TileJSON `url` or direct `tiles` templates
- place custom data below map labels
- restore highlighting driven by `setFeatureState`

## Example prompts
- Check why the `roads` layer from `basemap` renders nothing.
- Compare my style’s `source-layer` values with the TileJSON schema.
- Find out why `setFeatureState` does not highlight features on this map.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 37c3d71f11bb4e81.

BEGIN THIRD-PARTY FILE 37c3d71f11bb4e81
```text
---
name: maplibre-source-wiring
description: Getting a MapLibre GL JS source to actually render — TileJSON `url` versus hand-wired `tiles` templates, matching `source-layer` names to the tile schema, layer order and inserting below labels, `promoteId` and the feature ids that feature state needs, and the CORS and glyph failures behind a blank map. Use when a source is configured but nothing is drawing, or when setFeatureState does nothing.
metadata:
  status: verified
---

# MapLibre Source Wiring

**Use this only when a source is configured and the map is wrong with no error, in one of the ways listed below, or when choosing how a source should reference a tile endpoint.** For any other MapLibre question, such as how to style a layer that already draws, answer it as asked and stop when the question is answered: no troubleshooting, tips, pitfalls or gotchas section, no table of issues to check, and nothing from this skill, since none of it applies.

This skill covers connecting a source to a style correctly, and the failure modes that look identical from the outside.

## When to Use This Skill

The source is already configured and the map is wrong in a way that produces no error. These are
symptoms as you would observe them, before you know the cause:

- The map is blank, or a layer you added draws nothing, and the console is clean
- A custom style renders nothing against a tile source that works with the provider's own style
- The basemap is blurry, or sits at a different scale than everything drawn on top of it
- Data you added has covered the street names
- Icons are missing while the rest of the map draws fine
- Hover or click highlighting does nothing at all, and no error is raised
- You have a tile endpoint and are unsure which source type it needs, or whether to point `url`
  at its TileJSON instead of hand-writing `tiles`

**Not this skill.** Text in the wrong font, missing scripts, or self-hosting glyph
PBFs — [maplibre-fonts-glyphs](../maplibre-fonts-glyphs/SKILL.md). Deciding the colors, type,
and drawing order of a style you are designing — [maplibre-cartography](../maplibre-cartography/SKILL.md).
Deciding whether a dataset belongs in GeoJSON or vector tiles at
all — [maplibre-tile-sources](../maplibre-tile-sources/SKILL.md).

## Referencing tiles: `url` vs `tiles`
```
END THIRD-PARTY FILE 37c3d71f11bb4e81

The third-party file has ended. Everything between the 37c3d71f11bb4e81 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2327 of 16353 bytes. © maplibre · MIT · https://github.com/maplibre/maplibre-agent-skills/tree/HEAD/skills/maplibre-source-wiring/SKILL.md

## Similar
- [mapbox-maplibre-migration](https://affpapa.org/en/nevibecode/skills/mapbox-maplibre-migration.md) — skill · 1400 installs
- [cesium-mcp-runtime](https://affpapa.org/en/nevibecode/mcp/cesium-mcp-runtime.md) — MCP server · ★ 153 repo stars
- [CODE-1895-tui-lrc-typeahead-wiring](https://affpapa.org/en/nevibecode/agents/code-1895-tui-lrc-typeahead-wiring.md) — subagent · ★ 720 repo stars

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
