9 comprehensive Agent Skills that teach AI assistants how to build fast, beautiful, secure Mapbox applications across Web, iOS, and Android platforms. Covers performance optimization, cartographic design, framework integration, platform migration, and security best practices.
Install all Mapbox Agent Skills:
npx add-skill mapbox/mapbox-agent-skillsInstall specific skills:
npx add-skill mapbox/mapbox-agent-skills --skill mapbox-web-performance-patternsList available skills:
npx add-skill mapbox/mapbox-agent-skills --list💡 Pro tip: These skills work great on their own, but they're even more powerful when combined with the Mapbox MCP DevKit Server. Skills provide the expertise (performance patterns, design principles), while MCP tools provide the actions (create styles, generate previews). Together, they enable complete workflows from design to deployment.
Agent Skills are folders containing instructions and resources that AI assistants (like Claude Code, Cursor, GitHub Copilot) can discover and use to perform tasks more effectively. Unlike tools (which provide actions) or prompts (which provide workflows), skills provide domain expertise - the "know-how" that helps AI make informed decisions.
Think of skills as giving your AI assistant a specialized education in Mapbox development best practices.
Platform Coverage:
- 🌐 Web: React, Vue, Svelte, Angular, Next.js (Mapbox GL JS)
- 📱 iOS: Swift, SwiftUI, UIKit (Maps SDK for iOS)
- 📱 Android: Kotlin, Jetpack Compose, View system (Maps SDK for Android)
Migration guide between Mapbox GL JS and MapLibre GL JS in both directions.
Covers the fork history, API compatibility (~95% identical), token handling, style differences, and feature parity. Helps developers migrate in either direction or use both libraries together.
Use when:
- Migrating from Mapbox to MapLibre (or vice versa)
- Evaluating which library to use
- Understanding API compatibility
- Switching tile sources
- Combining MapLibre rendering with Mapbox APIs
Key topics:
- Fork history and license differences
- Package and import changes
- Token handling (Mapbox token vs no token)
- Style URL differences (mapbox:// vs OSM/custom)
- Feature parity comparison
- Plugin compatibility
- Migration in both directions
- When to choose each library
- Using both together
Covers:
- Step-by-step migration guides (both directions)
- API compatibility matrix (100% compatible vs minor differences)
- Common migration issues and solutions
- Decision guide (when to use which)
- Side-by-side code examples
Performance optimization patterns for building fast, efficient Mapbox GL JS web applications.
Covers initialization waterfalls, bundle size, rendering performance, memory management, and web optimization. Patterns are prioritized by impact on user experience (Critical → High Impact → Optimization).
Use when:
- Optimizing map load time and time-to-interactive
- Reducing bundle size or implementing code splitting
- Debugging slow rendering or janky interactions
- Managing thousands of markers or large datasets
- Optimizing for web browsers and low-end hardware
- Preventing memory leaks in long-running applications
Key topics:
- Eliminating initialization waterfalls (parallel loading, data fetching)
- Bundle size optimization (code splitting)
- Marker performance (HTML vs Canvas vs Symbol layers, clustering)
- Data loading strategies (GeoJSON vs vector tiles, viewport-based loading)
- Event handling optimization (debouncing, throttling)
- Memory management (cleanup patterns, feature state)
- Web-specific optimizations (browser performance, touch events)
Based on: Performance principles from Vercel's react-best-practices and Mapbox GL JS patterns
Expert guidance on map design principles, color theory, visual hierarchy, typography, and cartographic best practices.
Use when:
- Designing a new map style
- Choosing colors for map elements
- Making decisions about visual hierarchy
- Optimizing for specific use cases (navigation, data viz, etc.)
- Ensuring accessibility
- Creating themed maps (dark mode, vintage, etc.)
Key topics:
- Core cartographic principles (visual hierarchy, color theory)
- Typography best practices for maps
- Map context considerations (audience, platform, use case)
- Zoom level strategies
- Color palette templates
- Common mapping scenarios (restaurant finders, real estate, etc.)
Official integration patterns for Mapbox GL JS across popular web frameworks.
Covers React, Vue, Svelte, Angular, and Next.js with proper lifecycle management, token handling, and search integration. Based on Mapbox's create-web-app scaffolding tool.
Use when:
- Setting up Mapbox GL JS in a new web project
- Integrating Mapbox into a specific web framework
- Adding Mapbox Search functionality
- Implementing proper cleanup and lifecycle management
- Debugging map initialization issues in web apps
- Converting between frameworks
Key topics:
- Framework-specific patterns (React hooks, Vue composition API, Svelte stores, Angular services)
- Token management (environment variables across frameworks)
- Lifecycle management and cleanup (preventing memory leaks)
- Mapbox Search JS integration
- Common mistakes and how to avoid them
- SSR handling (Angular Universal, Next.js)
Integration patterns for Mapbox Maps SDK on iOS with Swift, SwiftUI, UIKit, and mobile optimization.
Covers Swift/SwiftUI integration, lifecycle management, token handling, offline maps, Navigation SDK, and battery/memory optimization for iOS devices.
Use when:
- Setting up Mapbox Maps SDK for iOS
- Integrating maps with SwiftUI or UIKit
- Managing token security in iOS apps
- Implementing offline map caching
- Adding turn-by-turn navigation
- Optimizing for battery life and memory
- Debugging crashes or performance issues on iOS
Key topics:
- SwiftUI UIViewRepresentable pattern
- UIKit lifecycle management (viewDidLoad, deinit)
- Token management (Info.plist, .xcconfig)
- Memory management and retain cycle prevention
- Offline map download and storage
- Navigation SDK integration
- Battery and network optimization
- Common iOS mistakes and solutions
Integration patterns for Mapbox Maps SDK on Android with Kotlin, Jetpack Compose, and mobile optimization.
Covers Kotlin/Jetpack Compose integration, lifecycle management, token handling, offline maps, Navigation SDK, and battery/memory optimization for Android devices.
Use when:
- Setting up Mapbox Maps SDK for Android
- Integrating maps with Jetpack Compose or View system
- Managing token security in Android apps
- Implementing offline map caching
- Adding turn-by-turn navigation
- Optimizing for battery life and memory
- Debugging crashes or performance issues on Android
Key topics:
- Jetpack Compose AndroidView pattern
- Activity/Fragment lifecycle management
- Token management (BuildConfig, local.properties)
- Memory management and leak prevention
- Offline map download and storage
- Navigation SDK integration
- Battery and network optimization
- Common Android mistakes and solutions
Common style patterns, layer configurations, and recipes for typical mapping scenarios.
Use when:
- Starting a new map style for a specific use case
- Looking for layer configuration examples
- Implementing common mapping patterns
- Optimizing existing styles
- Need proven recipes for typical scenarios
Key topics:
- Restaurant/POI finder pattern
- Real estate map pattern
- Data visualization base map pattern
- Navigation/routing map pattern
- Dark mode / night theme pattern
- Layer optimization patterns
- Common modifications (3D buildings, terrain, custom markers)
Expert guidance on validating, optimizing, and ensuring quality of Mapbox styles.
Covers validation, accessibility checks, and optimization techniques for production-ready styles.
Use when:
- Validating styles before production deployment
- Checking accessibility compliance (WCAG)
- Optimizing style file size and complexity
- Reviewing styles for common issues
- Setting up quality gates in CI/CD pipelines
Key topics:
- Style validation patterns
- Expression validation
- GeoJSON validation
- Color contrast checking (WCAG AA/AAA)
- Style optimization techniques
- Production readiness checklists
Security best practices for Mapbox access tokens.
Covers scope management, URL restrictions, rotation strategies, and incident response.
Use when:
- Creating new tokens
- Deciding between public vs secret tokens
- Setting up token restrictions
- Implementing token rotation
- Investigating security incidents
- Conducting security audits
Key topics:
- Token types and when to use them (public, secret, temporary)
- Scope management (principle of least privilege)
- URL restrictions and patterns
- Token storage and handling
- Rotation strategies
- Monitoring and auditing
- Incident response plans
Comprehensive migration guide for developers moving from Google Maps Platform to Mapbox GL JS.
Covers API equivalents, coordinate order gotchas, pattern translations, and step-by-step migration strategies with side-by-side code examples.
Use when:
- Migrating an existing Google Maps application to Mapbox
- Evaluating Mapbox as a Google Maps alternative
- Learning Mapbox with Google Maps background
- Translating Google Maps patterns to Mapbox
- Troubleshooting migration issues
Key topics:
- API equivalents (Map, Marker, Polygon, InfoWindow, etc.)
- Critical differences (lng,lat vs lat,lng coordinate order)
- Event mapping and handling changes
- Markers: Object-oriented vs data-driven approaches
- Geocoding, directions, and clustering comparisons
- Performance considerations (WebGL vs DOM)
- Custom styling: Map types vs style URLs
- Step-by-step migration strategy and checklist
- When NOT to migrate guidance
Covers all major features:
- Map initialization and configuration
- Markers (individual and data-driven)
- Popups/info windows
- Polygons, polylines, shapes
- Custom icons and symbols
- Geocoding and reverse geocoding
- Directions/routing
- Clustering (built-in vs MarkerClusterer)
- Controls and UI elements
- Framework integration (React, Vue, etc.)
Skills in this repository are automatically discovered by Claude Code when placed in:
# Install all skills
npx add-skill mapbox/mapbox-agent-skills
# Or manually symlink (for development)
mkdir -p .claude
ln -s ~/git/mapbox-agent-skills/skills .claude/skillsSkills are automatically activated when relevant to your task.
npx add-skill mapbox/mapbox-agent-skills -a cursornpx add-skill mapbox/mapbox-agent-skills -a vscodeThe add-skill CLI supports: OpenCode, Codex, Antigravity, and more. Run npx add-skill --help for full list.
Once installed, skills activate automatically when relevant:
👤 User: "My Mapbox map with 5,000 restaurant markers is slow. How do I optimize it?"
🤖 Claude: [Uses mapbox-web-performance-patterns skill]
"Based on the marker performance thresholds:
- < 100 markers: HTML markers OK
- 100-1,000: Use Symbol layers (GeoJSON)
- 1,000-10,000: Clustering required
-
10,000: Server-side clustering
For 5,000 markers, you need clustering. Here's the pattern..."
👤 User: "Set up Mapbox in my React app"
🤖 Claude: [Uses mapbox-web-integration-patterns skill]
"I'll use the React pattern with useRef + useEffect:
import { useRef, useEffect } from 'react';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';
function MapComponent() {
const mapRef = useRef(null);
const mapContainerRef = useRef(null);
useEffect(() => {
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
mapRef.current = new mapboxgl.Map({
container: mapContainerRef.current,
center: [-71.05953, 42.3629],
zoom: 13
});
// CRITICAL: Cleanup to prevent memory leaks
return () => {
mapRef.current.remove();
};
}, []);
return <div ref={mapContainerRef} style={{ height: '100vh' }} />;
}Key points:
- Use useRef for both map instance and container
- Initialize in useEffect with empty deps []
- Always return cleanup function that calls map.remove()
- Never initialize map in render (causes infinite loops)"
👤 User: "Create a map style for a restaurant finder app"
🤖 Claude: [Uses mapbox-cartography + mapbox-style-patterns skills]
"For a restaurant finder, you need:
Design (from cartography skill):
- High contrast for restaurant markers
- Muted background (food photos will overlay)
- Clear street labels for navigation
- Mobile-optimized design
Style pattern (from style-patterns skill): I'll apply the POI Finder pattern:
- Desaturated base map (#f5f5f5 background)
- Orange markers (#FF6B35) for visibility
- White roads on light gray background
- Simplified labels (only major streets) ..."
These Agent Skills work together with the Mapbox MCP DevKit Server:
| Component | Purpose | Example |
|---|---|---|
| Agent Skills (this repo) | Provide expertise | Performance patterns, design principles |
| MCP Tools | Execute actions | create_style_tool, list_tokens_tool |
| MCP Prompts | Orchestrate workflows | create-and-preview-style workflow |
Example workflow:
User: "Create a high-performance map for my restaurant finder"
1. [mapbox-cartography skill] → Understands restaurant maps need high contrast, muted background
2. [mapbox-token-security skill] → Creates token with only styles:read scope, URL restrictions
3. [mapbox-style-patterns skill] → Applies POI Finder pattern
4. [MCP style_builder_tool] → Generates style JSON
5. [MCP create_style_tool] → Creates style in Mapbox account
6. [mapbox-web-performance-patterns skill] → Recommends clustering for > 1,000 markers
7. [MCP preview_style_tool] → Generates preview link
Want to see these skills in action? Check out the examples/ directory for both conversation transcripts and working code examples.
Realistic conversation transcripts showing how AI assistants use the skills:
- Web Performance Optimization - Optimizing a map with 5,000 markers using mapbox-web-performance-patterns
- iOS SwiftUI Setup - Setting up Mapbox in SwiftUI using mapbox-ios-patterns
- Android Jetpack Compose Setup - Integrating Mapbox with Compose using mapbox-android-patterns
- Restaurant Finder Design - Designing a map style using mapbox-cartography + mapbox-style-patterns
Complete, runnable applications following skill patterns:
Web:
- react-map-basic - Basic React integration with proper lifecycle management
- performance-optimized - Advanced patterns: clustering, parallel loading, throttling
iOS:
- SwiftUIMapExample - SwiftUI integration with UIViewRepresentable pattern
Android:
- ComposeMapExample - Jetpack Compose integration with AndroidView pattern
Each example includes:
- ✅ Complete, working code
- ✅ Detailed README explaining patterns
- ✅ Comments highlighting key practices
- ✅ Setup and troubleshooting instructions
Each skill follows the Agent Skills specification:
skill-name/
├── SKILL.md # Main skill file (required)
│ ├── YAML frontmatter # name, description
│ └── Markdown content # Instructions and guidance
└── [optional files] # Additional resources
- Create a new directory in
skills/ - Create
SKILL.mdwith YAML frontmatter and instructions - Add reference materials (optional)
- Test with Claude Code or Cursor
- Submit a pull request
Guidelines:
- Keep instructions clear and actionable
- Provide concrete examples
- Include decision trees when applicable
- Reference official Mapbox documentation
- Test with real scenarios
To test skills locally:
# Clone repo
git clone https://github.com/mapbox/mapbox-agent-skills.git
cd mapbox-agent-skills
# Install in Claude Code
npx add-skill . -a claude-code
# Or symlink for development
mkdir -p .claude
ln -s $(pwd)/skills .claude/skillsTest with prompts like:
Web:
- "How do I optimize a Mapbox map with 50,000 markers?"
- "What's the best way to load large GeoJSON files?"
- "Set up Mapbox in my React app with proper cleanup"
- "Create a dark mode map style"
iOS:
- "Add Mapbox to my SwiftUI app"
- "How do I prevent memory leaks in my iOS map?"
- "Download offline maps for iOS"
- "Integrate Navigation SDK in my iOS app"
Android:
- "Integrate Mapbox with Jetpack Compose"
- "Handle lifecycle properly in my Android map Fragment"
- "Optimize battery usage for Android maps"
- "Set up offline regions for Android"
Agent Skills:
Mapbox Documentation:
- Mapbox Documentation
- Mapbox GL JS (Web)
- Maps SDK for iOS
- Maps SDK for Android
- Mapbox Style Specification
- Mapbox Tutorials
Related Tools:
We welcome contributions of new skills or improvements to existing ones! Please see our Contributing Guide for detailed instructions on creating skills, testing, and submitting pull requests.
For questions or suggestions, please open an issue.
MIT License - see LICENSE file for details.
Related Projects:
- Mapbox MCP DevKit Server - MCP server with tools for Mapbox development
- Mapbox GL JS - JavaScript library for interactive web maps
- Maps SDK for iOS - Native iOS mapping SDK
- Maps SDK for Android - Native Android mapping SDK
- Vercel Agent Skills - Agent Skills for React and Next.js