Mapbox Agent Skills
- Web, iOS, Android, and Flutter integration patterns
- Performance optimization and best practices
- Map design and cartography guidance
- Migration guides and common use cases
- MCP server integration patterns for AI agents
Mapbox Agent Skills are pre-built knowledge modules that teach AI assistants how to build Mapbox applications across web, iOS, Android, and Flutter platforms. These skills provide domain knowledge, best practices, and implementation patterns that help AI assistants make informed development decisions when working with Mapbox services.
What are Agent Skills?
Agent Skills are educational resources—not code or tools—that enhance AI assistant capabilities with specialized knowledge. They complement MCP servers by providing the "how-to knowledge" while MCP tools provide actionable capabilities, enabling complete development workflows.
For example, while the Mapbox MCP Server gives AI assistants the ability to call Mapbox APIs, and the DevKit MCP Server provides style management capabilities, Mapbox Agent Skills teach the AI how to use these tools effectively by providing:
- Framework-specific integration patterns
- Performance optimization strategies
- Design principles and best practices
- Migration guidance from other mapping platforms
- Common implementation patterns for typical use cases
Installation
Mapbox Agent Skills can be installed using the npx skills command, which works with Claude Code, Cursor, Visual Studio Code with GitHub Copilot, and other AI assistants.
Install All Skills
To install all 20 Mapbox Agent Skills at once:
npx skills add mapbox/mapbox-agent-skills
Install a Specific Skill
To install only a specific skill:
npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-integration-patterns
List Available Skills
To see all available skills before installing:
npx skills add mapbox/mapbox-agent-skills --list
Manual Installation
You can also manually clone the repository and link the skills:
Claude Code (project-specific):
git clone https://github.com/mapbox/mapbox-agent-skills.git
cd mapbox-agent-skills
mkdir -p .claude && ln -s ../skills .claude/skills
Global installation:
git clone https://github.com/mapbox/mapbox-agent-skills.git
cd mapbox-agent-skills
cp -r skills/* ~/.claude/skills/
Available Skills
Mapbox Agent Skills are organized into several categories based on their functionality.
Core Development Skills
Skills for integrating Mapbox into your applications across different platforms:
| Skill | Description |
|---|---|
mapbox-web-integration-patterns | Framework-specific integration guidance for React, Vue, Svelte, Angular, and Next.js with code examples and best practices. |
mapbox-ios-patterns | Swift and SwiftUI integration patterns for iOS applications with Mapbox Maps SDK. |
| mapbox-android-patterns | Kotlin and Jetpack Compose integration patterns for Android applications with Mapbox Maps SDK. |
| mapbox-flutter-patterns | Dart integration patterns for the Mapbox Maps SDK for Flutter, covering installation, platform setup, MapWidget initialization, annotations, and user location on iOS and Android. |
Performance & Optimization Skills
Skills focused on optimizing Mapbox application performance:
| Skill | Description |
|---|---|
mapbox-web-performance-patterns | Bundle size optimization, rendering performance, memory management, and best practices for high-performance web mapping applications. |
Design & Cartography Skills
Skills for creating effective and beautiful maps:
| Skill | Description |
|---|---|
mapbox-cartography | Design principles, color theory, visual hierarchy, and typography guidance for creating effective and beautiful maps. |
mapbox-style-patterns | Common style configurations for typical use cases including basemaps, data visualization, custom themes, and specialized mapping applications. |
mapbox-style-quality | Validation, optimization, accessibility guidance, and quality assurance practices for production-ready map styles. |
mapbox-data-visualization-patterns | Patterns for visualizing data on maps, including choropleth maps, heat maps, 3D visualizations, data-driven styling, and animated data. |
Search, Navigation & Geospatial Skills
Skills for working with Mapbox search, navigation, and geospatial operations:
| Skill | Description |
|---|---|
mapbox-search-integration | Complete search workflow implementation across web, iOS, and Android platforms. |
mapbox-search-patterns | Tool selection guidance and parameter optimization for Mapbox Search Box API, Geocoding API, and other search services. |
mapbox-geospatial-operations | Decision framework for choosing between geometric operations and routing APIs for geospatial calculations. |
mapbox-navigation-patterns | Navigation implementation patterns for turn-by-turn directions, route optimization, real-time traffic, multi-stop routing, and voice guidance across web, iOS, and Android. |
Common Use Case Skills
Skills for implementing common mapping patterns:
| Skill | Description |
|---|---|
mapbox-store-locator-patterns | Implementation patterns for store locators, restaurant finders, and location discovery applications. |
mapbox-google-maps-migration | Comprehensive migration guide from Google Maps to Mapbox with code examples and API equivalents. |
| mapbox-maplibre-migration | Guidance for switching between Mapbox GL JS and MapLibre GL JS with compatibility notes and code changes. |
Security Skills
Skills for secure Mapbox application development:
| Skill | Description |
|---|---|
mapbox-token-security | Token management best practices, rotation strategies, scope configurations, and security recommendations for production deployments. |
MCP Integration Skills
Skills for building AI agents and assistants that use Mapbox's MCP servers:
| Skill | Description |
|---|---|
mapbox-mcp-devkit-patterns | Integration patterns for the DevKit MCP Server in AI coding assistants, covering setup, style management, token management, and validation workflows. |
mapbox-mcp-runtime-patterns | Integration patterns for the Mapbox MCP Server in AI applications and agent frameworks, covering runtime integration with pydantic-ai, Mastra, LangChain, and custom agents. |
mapbox-location-grounding | Composes Mapbox MCP tools to produce grounded, cited location-aware responses from live data instead of stale or hallucinated training data. |
Using Skills with AI Assistants
Once installed, these skills are automatically available to your AI assistant. You can reference them in your conversations:
Example prompts:
- "Help me integrate Mapbox into my React application using best practices"
- "I need to optimize the performance of my Mapbox web app"
- "Show me how to implement a store locator with Mapbox"
- "I'm migrating from Google Maps to Mapbox, what do I need to know?"
The AI assistant will use the relevant skills to provide informed guidance based on Mapbox best practices and patterns.
Combining with MCP Servers
Mapbox Agent Skills work best when combined with Mapbox MCP servers:
- Mapbox MCP Server: Provides AI assistants with direct access to Mapbox web services APIs (directions, geocoding, isochrones, static maps, etc.)
- DevKit MCP Server: Enables AI assistants to manage styles, tokens, and access developer APIs
- Mapbox Agent Skills: Teaches AI assistants how to use these tools effectively with best practices and patterns
Together, these resources enable AI assistants to both understand Mapbox development best practices and take action through API calls, creating a comprehensive development workflow.
Repository Structure
The mapbox-agent-skills repository contains a /skills directory with individual folders for each skill. Each skill folder includes a SKILL.md file that documents the knowledge, patterns, and best practices for that specific domain.
Contributing
Mapbox Agent Skills is an open-source project. Contributions, suggestions, and feedback are welcome through the GitHub repository.