Introducing Mapbox Agent Skills

I'm excited to share something we've been working on that makes building with Mapbox a lot easier, especially if you're using AI coding assistants like Claude Code, Cursor, or GitHub Copilot.

We've built a collection of Agent Skills that teach AI assistants how to build better Mapbox applications. Think of it as giving your AI assistant a crash course in Mapbox development best practices.

TL;DR

Agent Skills teach AI assistants Mapbox development best practices. We've built 15 skills and counting covering web/iOS/Android integration, performance optimization, search implementation, geospatial operations, map design, migrations, security, and common patterns. Install them and your AI will know things like "cluster 1000+ markers" and "use Search Box API for autocomplete."

Install all skills:

npx add-skill mapbox/mapbox-agent-skills

Install specific skills:

npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns

List available skills:

npx skills add mapbox/mapbox-agent-skills --list

What Are Skills?

If you've been using AI coding assistants, you've probably noticed they're pretty good at writing code, but sometimes they miss the nuances. They might suggest patterns that work but aren't optimal, or miss important details about how things should be done.

Agent Skills are a way to fix this. They're folders with instructions and guidance that AI assistants can load and use when helping you build. Unlike tools (which let AI do things) or prompts (which give specific instructions), skills provide domain expertise. The know-how.

When an AI assistant has access to Mapbox skills, it knows things like "if you're adding 1000+ markers, you should use clustering" or "use the Search Box API for autocomplete, not the Geocoding API." It's the difference between an AI that knows how to code and one that knows how to code Mapbox apps specifically.

See It In Action

This production-ready store locator was built in minutes using Claude Code with Mapbox Agent Skills. The AI assistant handled marker patterns, distance calculations, search functionality, and responsive design automatically—following Mapbox best practices from the start.

Why Skills Are Important

Here's the thing: Mapbox has a lot of surface area. We have SDKs for web, iOS, and Android. We have multiple search APIs with different use cases. We have performance patterns that matter at scale. We have migration paths from other platforms.

When you're building with an AI assistant, you want it to know all this stuff. You don't want to spend time correcting it when it suggests using 1000 individual markers instead of clustering. You don't want it to miss that you should debounce search requests. You want it to just know.

That's what these skills do. They encode the knowledge we've built up from working with thousands of developers building Mapbox applications. The patterns that work. The mistakes to avoid. The right tool for the job.

What's Inside the Box

We've organized the skills into a few main areas. Here's what's available:

Platform Integration

Web, iOS, and Android patterns - These skills cover the fundamentals of integrating Mapbox into your app, whether you're building for the web with React, Vue, Svelte, or Angular, or going native with Swift/SwiftUI on iOS or Kotlin/Jetpack Compose on Android. They know about framework-specific patterns, lifecycle management, and platform best practices.

Performance

Web performance patterns - This one's huge. It covers everything from initialization strategies to handling thousands of markers, optimizing data loading, and managing memory. If you're building something that needs to perform at scale, this skill will save you a lot of debugging time.

Search

Search integration and patterns - We have two skills here. One walks through the complete workflow of adding search to your app (asking the right discovery questions, picking the right product, implementing it correctly). The other helps you choose between our different search tools and configure them properly. Between these two, your AI assistant will know exactly how to implement search for your use case.

Geospatial Operations

Geometric calculations and routing - This skill helps decide when to use offline geometric calculations (like measuring straight-line distance) versus when to use our routing APIs (like getting actual drive times). It's the "as the crow flies vs as the crow drives" decision framework, plus a ton of practical examples.

Design and Cartography

Map design, styles, and quality - Three skills covering cartographic principles (color theory, visual hierarchy, typography), common style patterns and layer configurations, and style validation and optimization. If you're doing custom map design, these will help you make maps that look professional and work well.

Migration

Google Maps and MapLibre migration - If you're moving from Google Maps Platform or MapLibre, these skills provide comprehensive migration guides with API equivalents and pattern translations. They know the gotchas and the breaking changes.

Security

Token security - Best practices for handling access tokens securely across all platforms. This is one of those things that's easy to get wrong, so having your AI assistant know the right patterns from the start is valuable.

Common Patterns

Store locators - A focused skill on building location finders and store locators, with patterns for markers, filtering, distance calculations, and all the UX details that make these features work well.

Getting Started

Installing skills is straightforward. If you're using Claude Code, Cursor, or another AI assistant that supports Agent Skills, you can add them all at once:

npx skills add mapbox/mapbox-agent-skills

Or install specific skills if you only need certain ones:

npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns

You can list what's available:

npx skills add mapbox/mapbox-agent-skills --list

Once installed, your AI assistant will automatically use these skills when you're working on Mapbox projects. You don't need to do anything special. Just start building and you'll notice better suggestions, fewer mistakes, and more production-ready code.

Pro tip: These skills work great with our Mapbox MCP servers. We have the Mapbox MCP Server for core Mapbox operations and the Mapbox MCP DevKit Server for development workflows. Skills provide the expertise (how to design good maps, which patterns to use), while MCP tools provide the actions (create styles, generate tokens, preview maps). Together they make a pretty powerful development workflow.

Build Stuff and Let Us Know

We built these skills based on what we've learned from years of working with developers building Mapbox applications. But they'll get better as more people use them and give us feedback.

If you build something cool with these skills, or if you find gaps where your AI assistant could use more guidance, let us know. Open an issue on GitHub or contribute a new skill if you've discovered patterns we should capture.

We're excited to see what you build.