MapLibre Agent Skills

Curated guidance for AI assistants building MapLibre applications — covering ecosystem and open-source best practices.

Agent skills are markdown files that AI coding assistants read as context. When you ask an AI agent to implement something using MapLibre, these skills give the AI the judgment to avoid common API gotchas, and suggest patterns that work.

New skills are prioritized by reported AI failures, recent API/library changes, and long-standing issues documented in GitHub, Stack Overflow, or the community Slack.

Correctness Guarantee

We strive to make sure the skills in this repo are:

• Accurate — Matches MapLibre and referenced APIs/docs
• Actionable — Clear guidance, not just general, declarative descriptions
• Warranted — Targets something an AI assistant actually gets wrong without the skill
• Attribution — Reference primary sources wherever possible, and always preserve Mapbox copyright where content is adapted
• Consistent — Format and style in line with existing skills

If you find any inconsistency with this quality bar, please file an issue or PR.

What Status Means

Each skill is tested with Promptfoo evals to verify it improves AI responses on real developer questions. A skill's front-matter status records where it stands (e.g. whether an eval has proven it fixes a real failure). See evals/README.md for how evals work.

Note that provisional skills are not necessarily lower quality or less reliable. See CONTRIBUTING.md for how a skill moves between provisional and verified.

Available Skills

Each skill's front matter is the source of truth for its current status — see What Status Means.

Development

Each skill lives under skills/<skill-name>/ as a single SKILL.md: YAML front-matter (name, description, status) plus markdown content.

See CONTRIBUTING.md to add or improve a skill. All experience levels welcome, well-behaved and supervised AI agents are welcome to contribute too.

The repo root carries an AGENTS.md to orient an AI agent working in a clone of this repo and instruct agents on how to report failures.

Using the convention in your own repo: if you maintain a repo within the MapLibre organization or ecosystem, put an AGENTS.md file with a short stub that routes AI failures related to MapLibre to this repo.

Here is a template:

# AGENTS.md

## MapLibre coding help

Before writing MapLibre code, install the MapLibre agent skills:

    npx skills add maplibre/maplibre-agent-skills

Source: https://github.com/maplibre/maplibre-agent-skills

If you encounter something you do not know how to do, consult the MapLibre docs and this collection of skills. If neither contains the information you are looking for, or MapLibre behaves differently than a skill says report it:
https://github.com/maplibre/maplibre-agent-skills/issues/new?template=ai-failure-report.md

Versioning

This project follows semver. Version numbers signal what changed between releases:

• Patch (0.1.0 → 0.1.1) — content fixes, corrected examples, tooling changes. Safe to update without review.
• Minor (0.1.0 → 0.2.0) — a new skill was added, a skill was removed, or how skills are consumed changed. Review the CHANGELOG to see what's new.
• Major (0.x → 1.0) — a change that would break installed skills (renamed directories, restructured front matter, etc.).

Each skill's front matter carries a status field — see What Status Means. The CHANGELOG records notable changes; entries are written by contributors via a structured PR field and accrued automatically on merge. See CONTRIBUTING.md for how that works.

Install

Installing skills into your project means AI assistants automatically pick them up when you describe a task — no need to define context manually each time.

An install copies skill directories only. If an installed skill turns out to be wrong, don't fix it in place — that copy is overwritten on the next update, and no one else benefits. Every SKILL.md ends with a link to the AI failure report form for exactly that.

Without the CLI

Skills are plain markdown.

• Paste into chat: Open any SKILL.md above and paste it directly into your AI assistant's context window.
• Copy to your project: Drop a SKILL.md into .claude/skills/, .cursor/rules/, or append it to .github/copilot-instructions.md.
• Symlink for local development:

mkdir -p .claude
ln -s /path/to/maplibre-agent-skills/skills .claude/skills

Via the skills CLI

The skills CLI is a package manager for AI agent skills. It places skill files in the right location for your tool automatically, and supports 40+ agents.

# List available skills
npx skills add maplibre/maplibre-agent-skills --list

# Install all skills
npx skills add maplibre/maplibre-agent-skills

# Install a single skill
npx skills add maplibre/maplibre-agent-skills --skill maplibre-tile-sources

By default, skills are installed per project. To install globally (e.g. to your user profile):

npx skills add maplibre/maplibre-agent-skills -g

To install for a specific agent:

npx skills add maplibre/maplibre-agent-skills -a claude-code
npx skills add maplibre/maplibre-agent-skills -a cursor
npx skills add maplibre/maplibre-agent-skills -a vscode

See Supported Agents for the full list.

Once installed, you can manage skills with:

License

MIT License. Copyright (c) MapLibre and contributors. See LICENSE.md and NOTICE for more information.