Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-navigation-patterns- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads mapbox-navigation-patterns automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Mapbox Navigation Patterns
Expert guidance for implementing navigation and routing features using Mapbox Directions API and Navigation SDKs. Covers turn-by-turn navigation, route optimization, real-time traffic integration, multi-stop routing, and navigation UI components.
Use This Skill When
User says things like:
- "I need turn-by-turn navigation in my app"
- "How do I add driving directions?"
- "I want to show a route on the map"
- "I need multi-stop routing"
- "How do I add voice guidance?"
- "I want real-time traffic updates"
- "I need to optimize delivery routes"
Product Overview
Directions API (REST)
Best for: Web applications, simple routing, backend route calculation
Features:
- Route calculation (driving, walking, cycling, traffic)
- Alternative routes
- Turn-by-turn instructions
- Multi-stop routing (up to 25 waypoints)
- Route optimization
- Real-time traffic data
- Avoid specific roads/areas
Pricing: Pay per request
Navigation SDK for iOS
Best for: Native iOS apps with turn-by-turn navigation
Defaults: SwiftUI app shell + wrap drop-in NavigationViewController via UIViewControllerRepresentable (official getting-started path). Use a fully custom Core UI (CoreSDKExample) only when the user explicitly wants to build their own nav chrome.
Before coding: SPM (MapboxNavigationCore + MapboxNavigationUIKit), MBXAccessToken, location permissions, background audio/location — see install guide and the iOS reference checklist. Stable Core/UIKit releases do not need a .netrc download token.
Features:
- Drop-in turn-by-turn UI (
NavigationViewController) — default - Optional fully custom Core UI (route progress / banner publishers)
- Voice guidance (30+ languages)
- Real-time rerouting
- Traffic-aware routing
- Offline maps and routing
- Route progress tracking
- Speed limit display
Pricing: Monthly Active Users (MAU) based
Navigation SDK for Android
Best for: Native Android apps with turn-by-turn navigation
Features:
- Complete turn-by-turn navigation UI
- Voice guidance (30+ languages)
- Real-time rerouting
- Traffic-aware routing
- Offline maps and routing
- Custom UI components
- Route progress tracking
- Speed limit display
Pricing: Monthly Active Users (MAU) based
Decision Guide
Choose Directions API when:
- ✅ Web application
- ✅ Simple route display (no turn-by-turn)
- ✅ Backend route calculation
- ✅ Route planning and optimization
- ✅ Multi-stop routing
- ✅ Don't need voice guidance
Choose Navigation SDK when:
- ✅ Native mobile app (iOS/Android)
- ✅ Need turn-by-turn navigation
- ✅ Need voice guidance
- ✅ Need navigation UI components
- ✅ Need offline navigation
- ✅ Need real-time rerouting
- ✅ Building a navigation/delivery app
Implementation Patterns
- references/web-directions-api.md - Directions API patterns for the web: basic route display, turn-by-turn instructions, alternative routes, multi-stop routing, route optimization, and congestion-based route coloring
- references/ios-navigation-sdk.md - When: iOS turn-by-turn, setup, default SwiftUI + wrapped
NavigationViewController, Core opt-in, example catalog - references/ios-navigation-specialized.md - When: multi-stop, route line, camera, road cameras, route alerts, or
NavigationMapViewcustomization - references/android-navigation-sdk.md - Navigation SDK for Android: basic turn-by-turn navigation, custom navigation UI, route line rendering, maneuver arrows, navigation camera, voice guidance
- references/android-performance-antipatterns.md - Android Navigation SDK performance and correctness antipatterns: Native Route Object traversal costs, threading, memory/lifecycle leaks, route management correctness, frequent-callback rendering efficiency, and Coordination API lifecycle
- references/best-practices.md - Route caching, error handling, performance optimization, user experience, and common use cases (delivery routing, ride-sharing ETAs, walking/cycling directions)
Related Skills
- mapbox-search-integration: Address search and geocoding
- mapbox-web-performance-patterns: Optimizing navigation performance
- mapbox-ios-patterns: iOS-specific integration patterns
- mapbox-android-patterns: Android-specific integration patterns
- mapbox-token-security: Securing your access tokens
Resources
- Directions API Documentation
- Navigation SDK for iOS
- Navigation SDK for Android
- Optimization API Documentation
- Map Matching API
- Navigation Products Overview
Quick Decision Guide
User says: "I need directions"
- Web app → Use Directions API
- Mobile app → Use Navigation SDK
User says: "I need turn-by-turn navigation"
- iOS → Navigation SDK for iOS (SwiftUI + wrapped
NavigationViewControllerby default; Core custom UI only if requested) - Android → Navigation SDK for Android
- Web → Use Directions API + custom UI (no voice guidance)
User says: "I need to optimize delivery routes" → Use Optimization API (multi-stop route optimization)
User says: "I need real-time traffic"
→ Use driving-traffic profile with Directions API or Navigation SDK
User says: "I need voice guidance" → Must use Navigation SDK (iOS/Android only)
User says: "Directions API or Navigation SDK?" → Native turn-by-turn / voice → Navigation SDK (MAU pricing). Web / route display only → Directions API (pay-per-request).
FAQ
What does the mapbox-navigation-patterns skill do?
Navigation implementation patterns for turn-by-turn directions, route optimization, real-time traffic, multi-stop routing, and voice guidance across web, iOS, and Android platforms
How do I install mapbox-navigation-patterns?
Run npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-navigation-patterns in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mapbox-navigation-patterns/ (personal) or .claude/skills/mapbox-navigation-patterns/ (project).
Which AI agents can use mapbox-navigation-patterns?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is mapbox-navigation-patterns safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains mapbox-navigation-patterns?
It is published by mapbox in mapbox/mapbox-agent-skills. It has 408 recorded installs.
More from mapbox/mapbox-agent-skills
mapbox-web-integration-patterns
mapbox/mapbox-agent-skills
Official integration patterns for Mapbox GL JS across popular web frameworks (React, Vue, Svelte, Angular). Covers setup, lifecycle management, token handling, search integration, and common pitfalls. Based on Mapbox's create-web-app scaffolding tool.
mapbox-web-performance-patterns
mapbox/mapbox-agent-skills
Performance optimization patterns for Mapbox GL JS web applications. Covers initialization waterfalls, bundle size, rendering performance, memory management, and web optimization. Prioritized by impact on user experience.
mapbox-style-patterns
mapbox/mapbox-agent-skills
Common style patterns, layer configurations, and recipes for typical mapping scenarios including restaurant finders, real estate, data visualization, navigation, delivery/logistics, and more. Use when implementing specific map use cases or looking for proven style patterns.
mapbox-geospatial-operations
mapbox/mapbox-agent-skills
Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs
mapbox-data-visualization-patterns
mapbox/mapbox-agent-skills
Patterns for visualizing data on maps including choropleth maps, heat maps, 3D visualizations, data-driven styling, and animated data. Covers layer types, color scales, and performance optimization.
mapbox-cartography
mapbox/mapbox-agent-skills
Expert guidance on map design principles, color theory, visual hierarchy, typography, and cartographic best practices for creating effective and beautiful maps with Mapbox. Use when designing map styles, choosing colors, or making cartographic decisions.
Popular mobile skills
design-mobile-apps
designed-by-ai/skills
Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.
ios-design
uizze.sh
Design and review iOS UI/UX for iPhone apps in SwiftUI, UIKit, or React Native. Use for mobile app design, screen redesigns, navigation flows, typography, forms, keyboard and safe-area layout, and accessibility checks. Apply Apple Human Interface Guidelines and consult real product references through the optional Uizze connection.
vercel-react-native-skills
vercel-labs/agent-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
animate-expo
emilkowalski/skills
Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use animate.
xcode-project-setup
firebase/agent-skills
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
firebase-remote-config-basics
firebase/agent-skills
Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.