Skip to content
Back to search

mapbox-agent-skills

MarketplaceWorks with Claude CodeGitHub

Comprehensive Agent Skills that teach AI assistants how to build fast, beautiful, secure Mapbox applications across Web, iOS, Android, and Flutter platforms. Covers performance optimization,…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mapbox/mapbox-agent-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mapbox/mapbox-agent-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mapbox-mapbox-agent-skills/badge.svg)](/listings/mapbox-mapbox-agent-skills)

HTML

<a href="/listings/mapbox-mapbox-agent-skills"><img src="/api/listings/mapbox-mapbox-agent-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Codex Plugin Local Testing

This repository includes a Codex plugin manifest at `plugins/mapbox/.codex-plugin/plugin.json` and a repo marketplace at `.agents/plugins/marketplace.json`.

Codex marketplaces currently expect a plugin subdirectory such as `plugins/mapbox`. To avoid maintaining a second tracked copy of every skill, keep editing the root `skills/` directory and generate the local plugin package before testing:

npm run build:codex-plugin
codex plugin marketplace add .
codex plugin marketplace list

Then restart Codex and install the `mapbox` plugin from the `Mapbox Agent Skills` marketplace.

The generated `plugins/mapbox/skills/` and `plugins/mapbox/.mcp.json` files are ignored by git.

Open Plugins (Cursor, Codex, GitHub Copilot, Claude Code)

This repository conforms to the [Open Plugins specification](https://open-plugins.com/), making it installable in any conformant tool - Cursor, Codex, GitHub Copilot, Claude Code, and more.

Add the marketplace source:

/plugin marketplace add mapbox/mapbox-agent-skills

Then install the plugin:

/plugin install mapbox

Claude Plugin (Claude Code)

Install as a Claude Code plugin to get skills and MCP servers in one step:

/plugin marketplace add mapbox/mapbox-agent-skills

Then install the plugin:

/plugin install mapbox

This adds all Mapbox skills and connects the `mapbox`, `mapbox-devkit`, and `mapbox-docs` MCP servers automatically.

Skills CLI

Install all Mapbox Agent Skills:

npx skills add 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

> **πŸ’‘ Pro tip:** These skills work great on their own, but they're even more powerful when combined with the [Mapbox MCP DevKit Server](https://github.com/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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json Β· Manifest Β· 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "mapbox-agent-skills",
  3. "owner": {
  4. "name": "Mapbox Plugin Marketplace",
  5. "email": "locationai@mapbox.com"
  6. },
  7. "metadata": {
  8. "description": "Official Mapbox plugin for Claude Code - skills and MCP servers for building location-aware applications with AI.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "mapbox",
  14. "description": "Mapbox skills and MCP servers for building location-aware applications with AI. Includes geospatial tools, style management, and patterns for web, iOS, Android, and AI agent frameworks.",
  15. "source": {
  16. "source": "github",
  17. "repo": "mapbox/mapbox-agent-skills"
  18. },
  19. "keywords": ["mapbox", "maps", "geospatial", "location", "mcp", "gis"]
  20. }
  21. ]
  22. }
README.md Β· README Β· 1,057 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Mapbox Agent Skills
  2. **Comprehensive Agent Skills** that teach AI assistants how to build fast, beautiful, secure Mapbox applications across **Web, iOS, Android, and Flutter** platforms. Covers performance optimization, cartographic design, framework integration, platform migration, search integration, geospatial operations, navigation, and security best practices.
  3. ## Quick Start
  4. ### Codex Plugin Local Testing
  5. This repository includes a Codex plugin manifest at `plugins/mapbox/.codex-plugin/plugin.json` and a repo marketplace at `.agents/plugins/marketplace.json`.
  6. Codex marketplaces currently expect a plugin subdirectory such as `plugins/mapbox`. To avoid maintaining a second tracked copy of every skill, keep editing the root `skills/` directory and generate the local plugin package before testing:
  7. ```bash
  8. npm run build:codex-plugin
  9. codex plugin marketplace add .
  10. codex plugin marketplace list
  11. ```
  12. Then restart Codex and install the `mapbox` plugin from the `Mapbox Agent Skills` marketplace.
  13. The generated `plugins/mapbox/skills/` and `plugins/mapbox/.mcp.json` files are ignored by git.
  14. ### Open Plugins (Cursor, Codex, GitHub Copilot, Claude Code)
  15. This repository conforms to the [Open Plugins specification](https://open-plugins.com/), making it installable in any conformant tool - Cursor, Codex, GitHub Copilot, Claude Code, and more.
  16. Add the marketplace source:
  17. ```
  18. /plugin marketplace add mapbox/mapbox-agent-skills
  19. ```
  20. Then install the plugin:
  21. ```
  22. /plugin install mapbox
  23. ```
  24. ### Claude Plugin (Claude Code)
  25. Install as a Claude Code plugin to get skills and MCP servers in one step:
  26. ```
  27. /plugin marketplace add mapbox/mapbox-agent-skills
  28. ```
  29. Then install the plugin:
  30. ```
  31. /plugin install mapbox
  32. ```
  33. This adds all Mapbox skills and connects the `mapbox`, `mapbox-devkit`, and `mapbox-docs` MCP servers automatically.
  34. ### Skills CLI
  35. Install all Mapbox Agent Skills:
  36. ```bash
  37. npx skills add mapbox/mapbox-agent-skills
  38. ```
  39. Install specific skills:
  40. ```bash
  41. npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns
  42. ```
  43. List available skills:
  44. ```bash
  45. npx skills add mapbox/mapbox-agent-skills --list
  46. ```
  47. > **πŸ’‘ Pro tip:** These skills work great on their own, but they're even more powerful when combined with the [Mapbox MCP DevKit Server](https://github.com/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.
  48. ## What are Agent Skills?
  49. 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.
  50. Think of skills as giving your AI assistant a specialized education in Mapbox development best practices.
  51. ## Available Skills
  52. **Platform Coverage:**
  53. - 🌐 **Web**: React, Vue, Svelte, Angular, Next.js (Mapbox GL JS)
  54. - πŸ“± **iOS**: Swift, SwiftUI, UIKit (Maps SDK for iOS)
  55. - πŸ“± **Android**: Kotlin, Jetpack Compose, View system (Maps SDK for Android)
  56. - πŸ“± **Flutter**: Dart (Maps SDK for Flutter, iOS and Android)
  57. ---
  58. ### πŸ—ΊοΈ mapbox-geospatial-operations
  59. **Expert guidance on choosing between offline geometric tools and routing APIs for geospatial operations.**
  60. Helps AI assistants select the right tool based on problem type (geometric vs routing), accuracy requirements, and performance needs. Features the "as the crow flies" vs "as the crow drives" decision framework.
  61. **Use when:**
  62. - Deciding between offline calculations and API calls
  63. - Calculating distances (straight-line vs road distance)
  64. - Checking if points are within an area
  65. - Creating travel-time zones vs distance buffers
  66. - Optimizing geospatial operations for performance
  67. - Understanding when to use routing vs geometry
  68. **Key topics:**
  69. - Decision framework: geometric operations vs routing APIs
  70. - Distance calculations (crow flies vs crow drives)
  71. - Proximity and containment checks
  72. - Area and shape operations
  73. - Routing and navigation patterns
  74. - Clustering and optimization
  75. - Hybrid approaches (combining tools)
  76. - Common anti-patterns to avoid
  77. - Performance and scale considerations
  78. **Tool categories covered:**
  79. - Offline geometric: distance, bearing, buffer, centroid, area, containment
  80. - Routing APIs: directions, matrix, optimization, isochrone, map matching
  81. [View skill β†’](./skills/mapbox-geospatial-operations/SKILL.md)
  82. ---
  83. ### πŸ” mapbox-search-integration
  84. **Complete workflow for implementing Mapbox search in applications from discovery to production.**
  85. Guides AI assistants through the entire search integration process: asking discovery questions, selecting the right product, implementing with best practices, and avoiding common pitfalls. Embodies collective knowledge from the Mapbox search team and customer learnings.
  86. **Use when:**
  87. - User needs to add search to their app
  88. - Implementing location search or geocoding
  89. - Need to ask the right questions about requirements
  90. - Want production-ready search implementation
  91. - Avoiding common integration mistakes
  92. **Key workflow:**
  93. 1. **Discovery questions** - What to ask users (POIs? Addresses? Geographic scope? Platform?)
  94. 2. **Product selection** - Search Box API vs Geocoding API, SDK vs direct API
  95. 3. **Implementation patterns** - Complete code examples for web, iOS, Android
  96. 4. **Best practices** - Debouncing, session tokens, error handling, UX patterns
  97. 5. **Common pitfalls** - What goes wrong and how to avoid it
  98. **Covers all platforms:**
  99. - Web (Mapbox Search JS React/Web/Core, Vue, Angular, Next.js)
  100. - iOS (Search SDK for iOS with UISearchController integration)
  101. - Android (Search SDK for Android with SearchView integration)
  102. - Node.js (Mapbox Search JS Core)
  103. **Best practices from "the good parts":**
  104. - βœ… Debouncing (prevent API spam)
  105. - βœ… Session token management (cost optimization)
  106. - βœ… Geographic filtering (better results)
  107. - βœ… Error handling (all failure cases)
  108. - βœ… Mobile UX (touch targets, keyboards)
  109. - βœ… Accessibility (keyboard nav, ARIA)
  110. - βœ… Caching strategies (high-volume apps)
  111. - βœ… Token security (proper scoping)
  112. [View skill β†’](./skills/mapbox-search-integration/SKILL.md)
  113. ---
  114. ### πŸ” mapbox-search-patterns
  115. **Expert guidance on choosing the right search tool and parameters for geocoding, POI search, and location discovery.**
  116. Helps AI assistants select between search_and_geocode, category_search, and reverse_geocode tools, and optimize parameters like proximity, bbox, country, limit, and more.
  117. **Use when:**
  118. - Choosing between search tools (specific names vs categories)
  119. - Setting up geocoding or POI search
  120. - Optimizing search parameters for accuracy
  121. - Implementing "near me" searches
  122. - Building autocomplete functionality
  123. - Troubleshooting search results
  124. **Key topics:**
  125. - Tool selection decision matrix (brands vs categories vs coordinates)
  126. - Parameter guidance (proximity, bbox, country, limit, types, ETA)
  127. - Common patterns ("near me", route-based search, multilingual)
  128. - Anti-patterns to avoid (missing proximity, wrong tool choice)
  129. - Performance optimization (minimizing API calls, appropriate limits)
  130. - Combining search with geospatial operations
  131. **Search tools covered:**
  132. - search_and_geocode_tool: Specific places, addresses, brands
  133. - category_search_tool: Generic categories, plural queries
  134. - reverse_geocode_tool: Coordinates to addresses
  135. [View skill β†’](./skills/mapbox-search-patterns/SKILL.md)
  136. ---
  137. ### πŸ”„ mapbox-maplibre-migration
  138. **Migration guide between Mapbox GL JS and MapLibre GL JS in both directions.**
  139. 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.
  140. **Use when:**
  141. - Migrating from Mapbox to MapLibre (or vice versa)
  142. - Evaluating which library to use
  143. - Understanding API compatibility
  144. - Switching tile sources
  145. - Combining MapLibre rendering with Mapbox APIs
  146. **Key topics:**
  147. - Fork history and license differences
  148. - Package and import changes
  149. - Token handling (Mapbox token vs no token)
  150. - Style URL differences (mapbox:// vs OSM/custom)
  151. - Feature parity comparison
  152. - Plugin compatibility
  153. - Migration in both directions
  154. - When to choose each library
  155. - Using both together
  156. **Covers:**
  157. - Step-by-step migration guides (both directions)
  158. - API compatibility matrix (100% compatible vs minor differences)
  159. - Common migration issues and solutions
  160. - Decision guide (when to use which)
  161. - Side-by-side code examples
  162. [View skill β†’](./skills/mapbox-maplibre-migration/SKILL.md)
  163. ---
  164. ### ⚑ mapbox-web-performance-patterns
  165. **Performance optimization patterns for building fast, efficient Mapbox GL JS web applications.**
  166. Covers initialization waterfalls, bundle size, rendering performance, memory management, and web optimization. Patterns are prioritized by impact on user experience (Critical β†’ High Impact β†’ Optimization).
  167. **Use when:**
  168. - Optimizing map load time and time-to-interactive
  169. - Reducing bundle size or implementing code splitting
  170. - Debugging slow rendering or janky interactions
  171. - Managing thousands of markers or large datasets
  172. - Optimizing for web browsers and low-end hardware
  173. - Preventing memory leaks in long-running applications
  174. **Key topics:**
  175. - Eliminating initialization waterfalls (parallel loading, data fetching)
  176. - Bundle size optimization (code splitting)
  177. - Marker performance (HTML vs Canvas vs Symbol layers, clustering)
  178. - Data loading strategies (GeoJSON vs vector tiles, viewport-based loading)
  179. - Event handling optimization (debouncing, throttling)
  180. - Memory management (cleanup patterns, feature state)
  181. - Web-specific optimizations (browser performance, touch events)
  182. **Based on:** Performance principles from [Vercel's react-best-practices](https://vercel.com/blog/introducing-react-best-practices) and Mapbox GL JS patterns
  183. [View skill β†’](./skills/mapbox-web-performance-patterns/SKILL.md)
  184. ---
  185. ### 🎨 mapbox-cartography
  186. **Expert guidance on map design principles, color theory, visual hierarchy, typography, and cartographic best practices.**
  187. **Use when:**
  188. - Designing a new map style
  189. - Choosing colors for map elements
  190. - Making decisions about visual hierarchy
  191. - Optimizing for specific use cases (navigation, data viz, etc.)
  192. - Ensuring accessibility
  193. - Creating themed maps (dark mode, vintage, etc.)
  194. **Key topics:**
  195. - Core cartographic principles (visual hierarchy, color theory)
  196. - Typography best practices for maps
  197. - Map context considerations (audience, platform, use case)
  198. - Zoom level strategies
  199. - Color palette templates
  200. - Common mapping scenarios (restaurant finders, real estate, etc.)
  201. [View skill β†’](./skills/mapbox-cartography/SKILL.md)
  202. ---
  203. ### πŸ”§ mapbox-web-integration-patterns
  204. **Official integration patterns for Mapbox GL JS across popular web frameworks and Web Components.**
  205. Covers React, Vue, Svelte, Angular, Next.js, and framework-agnostic Web Components (Custom Elements) with proper lifecycle management, token handling, and search integration. Based on Mapbox's `create-web-app` scaffolding tool.
  206. **Use when:**
  207. - Setting up Mapbox GL JS in a new web project
  208. - Integrating Mapbox into a specific web framework
  209. - Building framework-agnostic Web Components
  210. - Creating reusable component libraries
  211. - Adding Mapbox Search functionality
  212. - Implementing proper cleanup and lifecycle management
  213. - Debugging map initialization issues in web apps
  214. - Converting between frameworks
  215. **Key topics:**
  216. - Framework-specific patterns (React hooks, Vue composition API, Svelte stores, Angular services)
  217. - Web Components (Custom Elements, Shadow DOM, reactive attributes)
  218. - Token management (environment variables across frameworks)
  219. - Lifecycle management and cleanup (preventing memory leaks)
  220. - Mapbox Search JS integration
  221. - Common mistakes and how to avoid them
  222. - SSR handling (Angular Universal, Next.js)
  223. - Framework-agnostic patterns for maximum portability
  224. [View skill β†’](./skills/mapbox-web-integration-patterns/SKILL.md)
  225. ---
  226. ### πŸ“± mapbox-ios-patterns
  227. **Integration patterns for Mapbox Maps SDK on iOS with Swift, SwiftUI, UIKit, and mobile optimization.**
  228. Covers Swift/SwiftUI integration, lifecycle management, token handling, offline maps, Navigation SDK, and battery/memory optimization for iOS devices.
  229. **Use when:**
  230. - Setting up Mapbox Maps SDK for iOS
  231. - Integrating maps with SwiftUI or UIKit
  232. - Managing token security in iOS apps
  233. - Implementing offline map caching
  234. - Adding turn-by-turn navigation
  235. - Optimizing for battery life and memory
  236. - Debugging crashes or performance issues on iOS
  237. **Key topics:**
  238. - SwiftUI UIViewRepresentable pattern
  239. - UIKit lifecycle management (viewDidLoad, deinit)
  240. - Token management (Info.plist, .xcconfig)
  241. - Memory management and retain cycle prevention
  242. - Offline map download and storage
  243. - Navigation SDK integration
  244. - Battery and network optimization
  245. - Common iOS mistakes and solutions
  246. [View skill β†’](./skills/mapbox-ios-patterns/SKILL.md)
  247. ---
  248. ### πŸ“± mapbox-android-patterns
  249. **Integration patterns for Mapbox Maps SDK on Android with Kotlin, Jetpack Compose, and mobile optimization.**
  250. Covers Kotlin/Jetpack Compose integration, lifecycle management, token handling, offline maps, Navigation SDK, and battery/memory optimization for Android devices.
  251. **Use when:**
  252. - Setting up Mapbox Maps SDK for Android
  253. - Integrating maps with Jetpack Compose or View system
  254. - Managing token security in Android apps
  255. - Implementing offline map caching
  256. - Adding turn-by-turn navigation
  257. - Optimizing for battery life and memory
  258. - Debugging crashes or performance issues on Android
  259. **Key topics:**
  260. - Jetpack Compose AndroidView pattern
  261. - Activity/Fragment lifecycle management
  262. - Token management (BuildConfig, local.properties)
  263. - Memory management and leak prevention
  264. - Offline map download and storage
  265. - Navigation SDK integration
  266. - Battery and network optimization
  267. - Common Android mistakes and solutions
  268. [View skill β†’](./skills/mapbox-android-patterns/SKILL.md)
  269. ---
  270. ### πŸ“± mapbox-flutter-patterns
  271. **Official integration patterns for the Mapbox Maps SDK for Flutter (mapbox_maps_flutter) on iOS and Android with Dart.**
  272. Covers installation, iOS/Android platform setup, access token configuration, `MapWidget` initialization, camera control, annotations with tap handling, user location, and loading GeoJSON. Based on official Mapbox documentation.
  273. **Use when:**
  274. - Installing and configuring `mapbox_maps_flutter` in a Flutter app
  275. - Setting the Mapbox access token the right way
  276. - Initializing a `MapWidget` with camera / style options
  277. - Adding annotations (points, circles, lines, polygons) and handling taps
  278. - Showing the user location puck
  279. - Loading GeoJSON from app assets
  280. - Troubleshooting iOS build failures after adding Mapbox
  281. **Key topics:**
  282. - Dependency setup and iOS deployment target requirements
  283. - Access token configuration for Dart/iOS/Android
  284. - `MapWidget` and camera/style initialization
  285. - Annotations (points, circles, lines, polygons) and tap handling
  286. - User location puck
  287. - Loading GeoJSON from assets
  288. [View skill β†’](./skills/mapbox-flutter-patterns/SKILL.md)
  289. ---
  290. ### πŸ“ mapbox-style-patterns
  291. **Common style patterns, layer configurations, and recipes for typical mapping scenarios.**
  292. **Use when:**
  293. - Starting a new map style for a specific use case
  294. - Looking for layer configuration examples
  295. - Implementing common mapping patterns
  296. - Optimizing existing styles
  297. - Need proven recipes for typical scenarios
  298. **Key topics:**
  299. - Restaurant/POI finder pattern
  300. - Real estate map pattern
  301. - Data visualization base map pattern
  302. - Navigation/routing map pattern
  303. - Dark mode / night theme pattern
  304. - Layer optimization patterns
  305. - Common modifications (3D buildings, terrain, custom markers)
  306. [View skill β†’](./skills/mapbox-style-patterns/SKILL.md)
  307. ---
  308. ### βœ… mapbox-style-quality
  309. **Expert guidance on validating, optimizing, and ensuring quality of Mapbox styles.**
  310. Covers validation, accessibility checks, and optimization techniques for production-ready styles.
  311. **Use when:**
  312. - Validating styles before production deployment
  313. - Checking accessibility compliance (WCAG)
  314. - Optimizing style file size and complexity
  315. - Reviewing styles for common issues
  316. - Setting up quality gates in CI/CD pipelines
  317. **Key topics:**
  318. - Style validation patterns
  319. - Expression validation
  320. - GeoJSON validation
  321. - Color contrast checking (WCAG AA/AAA)
  322. - Style optimization techniques
  323. - Production readiness checklists
  324. [View skill β†’](./skills/mapbox-style-quality/SKILL.md)
  325. ---
  326. ### πŸ” mapbox-token-security
  327. **Security best practices for Mapbox access tokens.**
  328. Covers scope management, URL restrictions, rotation strategies, and incident response.
  329. **Use when:**
  330. - Creating new tokens
  331. - Deciding between public vs secret tokens
  332. - Setting up token restrictions
  333. - Implementing token rotation
  334. - Investigating security incidents
  335. - Conducting security audits
  336. **Key topics:**
  337. - Token types and when to use them (public, secret, temporary)
  338. - Scope management (principle of least privilege)
  339. - URL restrictions and patterns
  340. - Token storage and handling
  341. - Rotation strategies
  342. - Monitoring and auditing
  343. - Incident response plans
  344. [View skill β†’](./skills/mapbox-token-security/SKILL.md)
  345. ---
  346. ### πŸ“ mapbox-store-locator-patterns
  347. **Common patterns for building store locators, restaurant finders, and location-based search applications.**
  348. Comprehensive guide covering marker display strategies, filtering, distance calculation, interactive lists synced with maps, and directions integration. Perfect for building any location-based finder application.
  349. **Use when:**
  350. - Building store locator or restaurant finder applications
  351. - Displaying multiple locations on a map with interactive lists
  352. - Need filtering by category, distance, or search term
  353. - Calculate distances from user location
  354. - Show location details in popups or panels
  355. - Integrate directions to selected locations
  356. **Key topics:**
  357. - Marker strategies (HTML markers, symbol layers, clustering) based on location count
  358. - Interactive list/map synchronization
  359. - Search and category filtering
  360. - User location and distance calculation (Haversine formula)
  361. - Directions API integration
  362. - Performance optimization (debouncing, lazy loading, virtual scrolling)
  363. - Layout patterns (sidebar, overlay, mobile-responsive)
  364. **Covers all marker strategies:**
  365. - **< 100 locations**: HTML Markers with `mapboxgl.Marker()`
  366. - **100-1000 locations**: Symbol layers with GeoJSON
  367. - **> 1000 locations**: Clustering with aggregation
  368. **Common use cases:**
  369. - Store locators for retail chains
  370. - Restaurant finders with category filters
  371. - Office location directories
  372. - Real estate property search
  373. - Event venue finders
  374. - Service provider locators
  375. **Complete implementation:**
  376. - GeoJSON data structure
  377. - Map initialization and marker display
  378. - Interactive listing component
  379. - Search/filter functionality
  380. - Distance calculation and sorting
  381. - Popup/detail views
  382. - Directions integration
  383. - Responsive layouts
  384. [View skill β†’](./skills/mapbox-store-locator-patterns/SKILL.md)
  385. ---
  386. ### 🧭 mapbox-navigation-patterns
  387. **Quick reference for implementing navigation and routing with Mapbox Directions API and Navigation SDKs.**
  388. Covers web routing, turn-by-turn navigation, multi-stop routes, optimization, traffic-aware routing, and voice guidance across Web, iOS, and Android platforms.
  389. **Use when:**
  390. - Implementing routing and directions in applications
  391. - Adding turn-by-turn navigation (iOS/Android)
  392. - Building delivery route optimization
  393. - Showing traffic-aware routes
  394. - Need voice guidance for navigation
  395. - Calculating ETAs or route alternatives
  396. **Key topics:**
  397. - Directions API for web (basic routes, alternatives, multi-stop, optimization)
  398. - Navigation SDK for iOS (SwiftUI + wrapped NavigationViewController default; Core custom UI opt-in)
  399. - Navigation SDK for Android (NavigationView, custom UI, route progress)
  400. - Traffic-aware routing with congestion data
  401. - Route caching and performance optimization
  402. - Error handling and best practices
  403. **Covers all platforms:**
  404. - Web (Directions API with Mapbox GL JS)
  405. - iOS (Navigation SDK for iOS β€” SwiftUI + drop-in NavigationViewController by default)
  406. - Android (Navigation SDK for Android with Kotlin)
  407. **Common patterns:**
  408. - Basic route display on map
  409. - Alternative routes comparison
  410. - Multi-stop waypoint routing (up to 25 waypoints)
  411. - Route optimization for deliveries
  412. - Turn-by-turn instruction display
  413. - Traffic congestion visualization
  414. - Voice-guided navigation
  415. - Ride-sharing ETA calculations
  416. [View skill β†’](./skills/mapbox-navigation-patterns/SKILL.md)
  417. ---
  418. ### πŸ”„ mapbox-google-maps-migration
  419. **Comprehensive migration guide for developers moving from Google Maps Platform to Mapbox GL JS.**
  420. Covers API equivalents, coordinate order gotchas, pattern translations, and step-by-step migration strategies with side-by-side code examples.
  421. **Use when:**
  422. - Migrating an existing Google Maps application to Mapbox
  423. - Evaluating Mapbox as a Google Maps alternative
  424. - Learning Mapbox with Google Maps background
  425. - Translating Google Maps patterns to Mapbox
  426. - Troubleshooting migration issues
  427. **Key topics:**
  428. - API equivalents (Map, Marker, Polygon, InfoWindow, etc.)
  429. - Critical differences (lng,lat vs lat,lng coordinate order)
  430. - Event mapping and handling changes
  431. - Markers: Object-oriented vs data-driven approaches
  432. - Geocoding, directions, and clustering comparisons
  433. - Performance considerations (WebGL vs DOM)
  434. - Custom styling: Map types vs style URLs
  435. - Step-by-step migration strategy and checklist
  436. - When NOT to migrate guidance
  437. **Covers all major features:**
  438. - Map initialization and configuration
  439. - Markers (individual and data-driven)
  440. - Popups/info windows
  441. - Polygons, polylines, shapes
  442. - Custom icons and symbols
  443. - Geocoding and reverse geocoding
  444. - Directions/routing
  445. - Clustering (built-in vs MarkerClusterer)
  446. - Controls and UI elements
  447. - Framework integration (React, Vue, etc.)
  448. [View skill β†’](./skills/mapbox-google-maps-migration/SKILL.md)
  449. ---
  450. ### πŸ“Š mapbox-data-visualization-patterns
  451. **Patterns for visualizing data on Mapbox maps.**
  452. Covers choropleth maps, heat maps, clustering, bubble charts, 3D extrusions, and animated data layers. Includes data-driven styling with style expressions, color scales, and performance optimization.
  453. **Use when:**
  454. - Creating choropleth maps for statistics or demographics
  455. - Building heat maps for point density visualization
  456. - Clustering large datasets of point features
  457. - Implementing 3D building or elevation extrusions
  458. - Applying data-driven styles based on feature properties
  459. - Animating data over time
  460. **Key topics:**
  461. - Visualization type selection (choropleth, heat map, clustering, bubble, 3D, flow)
  462. - Style expressions for data-driven rendering
  463. - Color scales and interpolation
  464. - GeoJSON data structures
  465. - Layer type selection (`fill`, `heatmap`, `circle`, `fill-extrusion`, `line`)
  466. - Performance optimization for large datasets
  467. [View skill β†’](./skills/mapbox-data-visualization-patterns/SKILL.md)
  468. ---
  469. ### πŸ€– mapbox-mcp-devkit-patterns
  470. **Integration patterns for Mapbox MCP DevKit Server in AI coding assistants.**
  471. Setup and usage guide for the [Mapbox MCP DevKit Server](https://github.com/mapbox/mcp-devkit-server) β€” an MCP server for AI coding workflows. Covers style management, token creation, data validation, and documentation access through Claude Code, Cursor, and other AI assistants.
  472. **Use when:**
  473. - Setting up Mapbox MCP DevKit in Claude Code, Cursor, Claude Desktop, or VS Code
  474. - Creating and iterating on map styles with AI assistance
  475. - Generating scoped access tokens for different environments
  476. - Validating GeoJSON, style expressions, or checking color contrast
  477. - Looking up Mapbox documentation through your AI coding assistant
  478. **Key topics:**
  479. - Setup for Claude Code, Claude Desktop, Cursor, VS Code with Copilot
  480. - Style management (create, update, preview, compare, validate)
  481. - Token management with scoped permissions and URL restrictions
  482. - GeoJSON and style expression validation
  483. - Geographic utilities (bounding boxes, coordinate conversion)
  484. - Dev/staging/prod environment setup
  485. [View skill β†’](./skills/mapbox-mcp-devkit-patterns/SKILL.md)
  486. ---
  487. ### 🌐 mapbox-mcp-runtime-patterns
  488. **Integration patterns for Mapbox MCP Server in AI applications and agent frameworks.**
  489. Patterns for integrating the [Mapbox MCP Server](https://github.com/mapbox/mcp-server) into production AI applications. Covers all major Python and TypeScript agent frameworks with working examples and correct API usage.
  490. **Use when:**
  491. - Integrating geospatial capabilities into AI agents (Pydantic AI, CrewAI, Smolagents, LangChain, Mastra)
  492. - Building location-aware applications (real estate, food delivery, travel planning)
  493. - Choosing between offline Turf.js tools vs. Mapbox API tools
  494. - Optimizing geospatial operations (caching, batching, tool selection)
  495. - Building Zillow-style, DoorDash-style, or TripAdvisor-style AI features
  496. **Key topics:**
  497. - Framework-specific patterns (Pydantic AI, CrewAI, Smolagents, LangChain, Mastra)
  498. - Offline tools (distance, bearing, point-in-polygon, area β€” free, instant)
  499. - API tools (directions, geocoding, isochrone, POI search β€” real-time data)
  500. - Correct coordinate format (`{longitude, latitude}` objects)
  501. - Tool description writing for accurate LLM tool selection
  502. - Performance optimization and error handling
  503. [View skill β†’](./skills/mapbox-mcp-runtime-patterns/SKILL.md)
  504. ---
  505. ### πŸ›°οΈ mapbox-location-grounding
  506. **Compose Mapbox MCP tools to produce grounded, cited location-aware responses from live data instead of training data.**
  507. Teaches AI assistants how to ground location-aware responses in live Mapbox data by composing MCP tools into a structured, cited answer, instead of relying on stale or hallucinated training data for place names, POIs, ratings, or travel times.
  508. **Use when:**
  509. - Answering "what's near [location]?" or describing a neighborhood/area
  510. - Finding places within walking/driving distance
  511. - Answering travel-time or distance questions between locations
  512. - Building real estate, travel, mobility, or local discovery features
  513. - Any location question where accuracy, recency, or travel time matters
  514. **Key topics:**
  515. - Preferring `ground_location_tool` for one-call grounding (reverse geocoding, POI search, place details, isochrone, static map)
  516. - Manual tool composition fallback when `ground_location_tool` isn't available
  517. - Category/subcategory query conventions vs. unsupported attribute preferences
  518. - Citing data sources in the final response
  519. [View skill β†’](./skills/mapbox-location-grounding/SKILL.md)
  520. ---
  521. ## How Skills Work
  522. ### With Claude Code
  523. Skills in this repository are automatically discovered by Claude Code when placed in:
  524. ```bash
  525. # Install all skills
  526. npx skills add mapbox/mapbox-agent-skills
  527. # Or manually symlink (for development)
  528. mkdir -p .claude
  529. ln -s ~/git/mapbox-agent-skills/skills .claude/skills
  530. ```
  531. Skills are automatically activated when relevant to your task.
  532. ### With Cursor
  533. ```bash
  534. npx skills add mapbox/mapbox-agent-skills -a cursor
  535. ```
  536. ### With VS Code (GitHub Copilot)
  537. ```bash
  538. npx skills add mapbox/mapbox-agent-skills -a vscode
  539. ```
  540. ### With Other AI Assistants
  541. The `skills` CLI supports: OpenCode, Codex, Antigravity, and more. Run `npx skills add --help` for full list.
  542. ### Manual Installation
  543. If your AI assistant doesn't support the `skills` CLI, you can copy skill files directly:
  544. ```bash
  545. # For Claude Code β€” copy SKILL.md into .claude/skills/
  546. mkdir -p .claude/skills/mapbox-web-performance-patterns
  547. curl -o .claude/skills/mapbox-web-performance-patterns/SKILL.md \
  548. https://raw.githubusercontent.com/mapbox/mapbox-agent-skills/main/skills/mapbox-web-performance-patterns/SKILL.md
  549. # For Codex, Copilot, and other AGENTS.md-based tools β€” copy to project root
  550. curl -O https://raw.githubusercontent.com/mapbox/mapbox-agent-skills/main/skills/mapbox-web-performance-patterns/AGENTS.md
  551. ```
  552. ## Example Usage
  553. Once installed, skills activate automatically when relevant:
  554. ### Performance Optimization
  555. πŸ‘€ User: "My Mapbox map with 5,000 restaurant markers is slow. How do I optimize it?"
  556. πŸ€– Claude: [Uses mapbox-web-performance-patterns skill]
  557. "Based on the marker performance thresholds:
  558. - < 100 markers: HTML markers OK
  559. - 100-1,000: Use Symbol layers (GeoJSON)
  560. - 1,000-10,000: Clustering required
  561. - > 10,000: Server-side clustering
  562. For 5,000 markers, you need clustering. Here's the pattern..."
  563. ### Framework Integration
  564. πŸ‘€ User: "Set up Mapbox in my React app"
  565. πŸ€– Claude: [Uses mapbox-web-integration-patterns skill]
  566. "I'll use the React pattern with useRef + useEffect:
  567. ```jsx
  568. import { useRef, useEffect } from 'react';
  569. import mapboxgl from 'mapbox-gl';
  570. import 'mapbox-gl/dist/mapbox-gl.css';
  571. function MapComponent() {
  572. const mapRef = useRef(null);
  573. const mapContainerRef = useRef(null);
  574. useEffect(() => {
  575. mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
  576. mapRef.current = new mapboxgl.Map({
  577. container: mapContainerRef.current,
  578. center: [-71.05953, 42.3629],
  579. zoom: 13
  580. });
  581. // CRITICAL: Cleanup to prevent memory leaks
  582. return () => {
  583. mapRef.current.remove();
  584. };
  585. }, []);
  586. return <div ref={mapContainerRef} style={{ height: '100vh' }} />;
  587. }
  588. ```
  589. Key points:
  590. - Use useRef for both map instance and container
  591. - Initialize in useEffect with empty deps []
  592. - Always return cleanup function that calls map.remove()
  593. - Never initialize map in render (causes infinite loops)"
  594. ### Map Design
  595. πŸ‘€ User: "Create a map style for a restaurant finder app"
  596. πŸ€– Claude: [Uses mapbox-cartography + mapbox-style-patterns skills]
  597. "For a restaurant finder, you need:
  598. Design (from cartography skill):
  599. - High contrast for restaurant markers
  600. - Muted background (food photos will overlay)
  601. - Clear street labels for navigation
  602. - Mobile-optimized design
  603. Style pattern (from style-patterns skill):
  604. I'll apply the POI Finder pattern:
  605. - Desaturated base map (#f5f5f5 background)
  606. - Orange markers (#FF6B35) for visibility
  607. - White roads on light gray background
  608. - Simplified labels (only major streets)
  609. ..."
  610. ## How Skills Complement Mapbox MCP Server
  611. These Agent Skills work together with the [Mapbox MCP DevKit Server](https://github.com/mapbox/mcp-devkit-server):
  612. | Component | Purpose | Example |
  613. | ---------------------------- | --------------------- | --------------------------------------- |
  614. | **Agent Skills** (this repo) | Provide expertise | Performance patterns, design principles |
  615. | **MCP Tools** | Execute actions | `create_style_tool`, `list_tokens_tool` |
  616. | **MCP Prompts** | Orchestrate workflows | `create-and-preview-style` workflow |
  617. **Example workflow:**
  618. ```
  619. User: "Create a high-performance map for my restaurant finder"
  620. 1. [mapbox-cartography skill] β†’ Understands restaurant maps need high contrast, muted background
  621. 2. [mapbox-token-security skill] β†’ Creates token with only styles:read scope, URL restrictions
  622. 3. [mapbox-style-patterns skill] β†’ Applies POI Finder pattern
  623. 4. [MCP style_builder_tool] β†’ Generates style JSON
  624. 5. [MCP create_style_tool] β†’ Creates style in Mapbox account
  625. 6. [mapbox-web-performance-patterns skill] β†’ Recommends clustering for > 1,000 markers
  626. 7. [MCP preview_style_tool] β†’ Generates preview link
  627. ```
  628. ## Examples
  629. Want to see these skills in action? Check out the [`examples/`](./examples/) directory for both conversation transcripts and working code examples.
  630. ### πŸ“ Conversation Examples
  631. Realistic conversation transcripts showing how AI assistants use the skills:
  632. - [Web Performance Optimization](./examples/conversations/web-performance-optimization.md) - Optimizing a map with 5,000 markers using **mapbox-web-performance-patterns**
  633. - [iOS SwiftUI Setup](./examples/conversations/ios-swiftui-setup.md) - Setting up Mapbox in SwiftUI using **mapbox-ios-patterns**
  634. - [Android Jetpack Compose Setup](./examples/conversations/android-compose-setup.md) - Integrating Mapbox with Compose using **mapbox-android-patterns**
  635. - [Restaurant Finder Design](./examples/conversations/restaurant-finder-design.md) - Designing a map style using **mapbox-cartography** + **mapbox-style-patterns**
  636. ### πŸ’» Working Code Examples
  637. Complete, runnable applications following skill patterns:
  638. **Web:**
  639. - [react-map-basic](./examples/web/react-map-basic/) - Basic React integration with proper lifecycle management
  640. - [performance-optimized](./examples/web/performance-optimized/) - Advanced patterns: clustering, parallel loading, throttling
  641. **iOS:**
  642. - [SwiftUIMapExample](./examples/ios/SwiftUIMapExample/) - SwiftUI integration with UIViewRepresentable pattern
  643. **Android:**
  644. - [ComposeMapExample](./examples/android/ComposeMapExample/) - Jetpack Compose integration with AndroidView pattern
  645. Each example includes:
  646. - βœ… Complete, working code
  647. - βœ… Detailed README explaining patterns
  648. - βœ… Comments highlighting key practices
  649. - βœ… Setup and troubleshooting instructions
  650. [**β†’ Browse all examples**](./examples/)
  651. ## Development
  652. ### Structure
  653. Each skill follows this structure:
  654. ```
  655. skill-name/
  656. β”œβ”€β”€ SKILL.md # Main skill file (required)
  657. β”‚ β”œβ”€β”€ YAML frontmatter # name, description
  658. β”‚ └── Markdown content # Instructions and guidance
  659. └── [optional files] # Additional resources
  660. ```
  661. ### Creating Custom Skills
  662. 1. Create a new directory in `skills/`
  663. 2. Create `SKILL.md` with YAML frontmatter and instructions
  664. 3. Add reference materials (optional)
  665. 4. Test with Claude Code or Cursor
  666. 5. Submit a pull request
  667. **Guidelines:**
  668. - Keep instructions clear and actionable
  669. - Provide concrete examples
  670. - Include decision trees when applicable
  671. - Reference official Mapbox documentation
  672. - Test with real scenarios
  673. ### Testing
  674. To test skills locally:
  675. ```bash
  676. # Clone repo
  677. git clone https://github.com/mapbox/mapbox-agent-skills.git
  678. cd mapbox-agent-skills
  679. # Install in Claude Code
  680. npx skills add . -a claude-code
  681. # Or symlink for development
  682. mkdir -p .claude
  683. ln -s $(pwd)/skills .claude/skills
  684. ```
  685. Test with prompts like:
  686. **Web:**
  687. - "How do I optimize a Mapbox map with 50,000 markers?"
  688. - "What's the best way to load large GeoJSON files?"
  689. - "Set up Mapbox in my React app with proper cleanup"
  690. - "Create a dark mode map style"
  691. **iOS:**
  692. - "Add Mapbox to my SwiftUI app"
  693. - "How do I prevent memory leaks in my iOS map?"
  694. - "Download offline maps for iOS"
  695. - "Integrate Navigation SDK in my iOS app"
  696. **Android:**
  697. - "Integrate Mapbox with Jetpack Compose"
  698. - "Handle lifecycle properly in my Android map Fragment"
  699. - "Optimize battery usage for Android maps"
  700. - "Set up offline regions for Android"
  701. ## Resources
  702. **Mapbox Documentation:**
  703. - [Mapbox Documentation](https://docs.mapbox.com)
  704. - [Mapbox GL JS (Web)](https://docs.mapbox.com/mapbox-gl-js/guides/)
  705. - [Maps SDK for iOS](https://docs.mapbox.com/ios/maps/guides/)
  706. - [Maps SDK for Android](https://docs.mapbox.com/android/maps/guides/)
  707. - [Mapbox Style Specification](https://docs.mapbox.com/style-spec/)
  708. - [Mapbox Tutorials](https://docs.mapbox.com/help/tutorials/)
  709. **Related Tools:**
  710. - [Mapbox MCP DevKit Server](https://github.com/mapbox/mcp-devkit-server)
  711. ## Contributing
  712. We welcome contributions of new skills or improvements to existing ones! Please see our [Contributing Guide](./CONTRIBUTING.md) for detailed instructions on creating skills, testing, and submitting pull requests.
  713. For questions or suggestions, please [open an issue](https://github.com/mapbox/mapbox-agent-skills/issues).
  714. ## License
  715. MIT License - see [LICENSE](LICENSE.md) file for details.
  716. ---
  717. **Related Projects:**
  718. - [Mapbox MCP DevKit Server](https://github.com/mapbox/mcp-devkit-server) - MCP server with tools for Mapbox development
  719. - [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) - JavaScript library for interactive web maps
  720. - [Maps SDK for iOS](https://docs.mapbox.com/ios/maps/guides/) - Native iOS mapping SDK
  721. - [Maps SDK for Android](https://docs.mapbox.com/android/maps/guides/) - Native Android mapping SDK
  722. - [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills) - Agent Skills for React and Next.js

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.