Mapbox Agent Skills
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, search integration, geospatial operations, and security best practices.
Quick Start
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, 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. 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 are Agent Skills?
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.
Available Skills
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)
🗺️ mapbox-geospatial-operations
Expert guidance on choosing between offline geometric tools and routing APIs for geospatial operations.
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.
Use when:
- Deciding between offline calculations and API calls
- Calculating distances (straight-line vs road distance)
- Checking if points are within an area
- Creating travel-time zones vs distance buffers
- Optimizing geospatial operations for performance
- Understanding when to use routing vs geometry
Key topics:
- Decision framework: geometric operations vs routing APIs
- Distance calculations (crow flies vs crow drives)
- Proximity and containment checks
- Area and shape operations
- Routing and navigation patterns
- Clustering and optimization
- Hybrid approaches (combining tools)
- Common anti-patterns to avoid
- Performance and scale considerations
Tool categories covered:
- Offline geometric: distance, bearing, buffer, centroid, area, containment
- Routing APIs: directions, matrix, optimization, isochrone, map matching
View skill →
🔍 mapbox-search-integration
Complete workflow for implementing Mapbox search in applications from discovery to production.
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.
Use when:
