[skills] Add Mapbox Agent Skills for domain expertise #47

mattpodwysocki · 2025-12-19T06:36:31Z

Summary

Adds three comprehensive Agent Skills that provide domain expertise to AI assistants working with Mapbox. Skills complement MCP tools (which provide capabilities) and prompts (which provide workflows) by teaching AI assistants how to make informed decisions about map design, security, and patterns.

Key Distinction:

MCP Tools: Execute actions (create_style_tool, list_tokens_tool)
MCP Prompts: Orchestrate workflows (setup-mapbox-project, debug-mapbox-integration)
Agent Skills: Provide expertise (cartography principles, security best practices)

New Skills

🎨 mapbox-cartography (~300 lines)

Expert guidance on map design principles:

Core cartographic principles (visual hierarchy, color theory, typography)
Zoom level strategies
Color palette templates (light, dark, high-contrast, vintage)
Common mapping scenarios (restaurant finders, real estate, data viz, navigation)
Performance optimization and accessibility

🔐 mapbox-token-security (~490 lines)

Security best practices for token management:

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 (scheduled and emergency)
Monitoring, auditing, and incident response

📐 mapbox-style-patterns (~800 lines)

Common implementation patterns with full code examples:

5 complete style patterns with JSON layer configurations:
- Restaurant/POI Finder
- Real Estate Map
- Data Visualization Base Map
- Navigation/Routing Map
- Dark Mode Theme
Decision trees for pattern selection
Layer optimization patterns
Common modifications (3D buildings, terrain, custom markers)

Documentation

Complete skills/README.md with:
- Overview of Agent Skills concept
- Usage instructions for Claude Code, Claude API, and Claude.ai
- Skill structure documentation
- How skills work with the MCP server
- Contribution guidelines
Updated main README.md with skills section
Updated CLAUDE.md with skills architecture

File Structure

skills/
├── README.md
├── mapbox-cartography/
│   └── SKILL.md
├── mapbox-token-security/
│   └── SKILL.md
└── mapbox-style-patterns/
    └── SKILL.md

Usage Example

With skills, when a user asks "Create a map for my restaurant finder app", Claude will:

[mapbox-cartography] Understand that restaurant maps need high-contrast markers, muted backgrounds, clear navigation labels
[mapbox-token-security] Create tokens with proper scopes and URL restrictions
[mapbox-style-patterns] Apply the POI Finder pattern with proven configurations
[MCP Tools] Execute the implementation using the DevKit tools

Relationship to Other PRs

This PR is independent of the prompts PR (#46). They can be merged in any order:

Prompts provide workflows (multi-step task orchestration)
Skills provide expertise (domain knowledge and best practices)
Both complement the existing MCP tools

Testing

No code changes - all skills are markdown files that are consumed by Claude Code/API/Claude.ai. Skills have been tested manually with Claude Code to verify:

✅ YAML frontmatter parses correctly
✅ Content is well-structured and actionable
✅ Examples are accurate and complete
✅ Documentation is comprehensive

🤖 Generated with Claude Code

Add three Agent Skills that provide domain expertise complementing the MCP server's tools and prompts: 1. mapbox-cartography: Map design principles, color theory, visual hierarchy, typography, and cartographic best practices. Teaches Claude how to make informed design decisions. 2. mapbox-token-security: Security best practices for token management including scope control, URL restrictions, rotation strategies, and incident response. 3. mapbox-style-patterns: Common style patterns and layer configurations for typical mapping scenarios (restaurant finders, real estate, data viz, navigation, dark mode). Skills work alongside MCP components: - MCP Tools: Execute actions (create_style_tool) - MCP Prompts: Orchestrate workflows (create-and-preview-style) - Agent Skills: Provide expertise (design principles, security) Skills are filesystem-based and discoverable by Claude Code, uploadable to Claude API, or usable in Claude.ai. Documentation includes: - Complete skills/README.md with usage instructions - Updated main README.md with skills section - Updated CLAUDE.md with architecture notes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

- Resolved conflict by including both Agent Skills and Prompts sections - Agent Skills section appears first, followed by Prompts section - All prompts from main are now included in this branch

mattpodwysocki · 2025-12-19T17:29:19Z

✅ Merge conflict resolved!

The README conflict between Skills and Prompts has been resolved. This branch now includes:

✅ Agent Skills (3 comprehensive skill files)
✅ MCP Prompts (merged from main - 6 prompts total)
✅ Both sections in README (Skills → Prompts → Resources)

The branch is now up to date with main and ready for review.

Adds comprehensive framework integration patterns based on create-web-app: New Skill: mapbox-integration-patterns - React pattern (useRef + useEffect + cleanup) - Vue pattern (mounted + unmounted) - Svelte pattern (onMount + onDestroy) - Angular pattern (ngOnInit + ngOnDestroy + SSR handling) - Vanilla JS patterns (with and without bundler) - Next.js patterns (App Router and Pages Router) Key Topics: - Framework-specific lifecycle management - Proper cleanup to prevent memory leaks - Token management across different bundlers - Mapbox Search JS integration - Common mistakes and how to avoid them - SSR handling for Angular and Next.js - Testing patterns for maps Based on official patterns from: https://github.com/mapbox/create-web-app This complements existing skills: - mapbox-cartography: Design principles - mapbox-token-security: Security best practices - mapbox-style-patterns: Common style configurations 🤖 Generated with Claude Code

mattpodwysocki · 2025-12-19T19:21:19Z

✨ New skill added: mapbox-integration-patterns

Based on the team's scaffolding tool, I've added a comprehensive 4th skill:

🔧 mapbox-integration-patterns

What it covers:

✅ React integration (useRef + useEffect + cleanup)
✅ Vue integration (mounted + unmounted)
✅ Svelte integration (onMount + onDestroy)
✅ Angular integration (ngOnInit + ngOnDestroy + SSR)
✅ Vanilla JS (with and without bundler)
✅ Next.js patterns (App Router + Pages Router)
✅ Mapbox Search JS integration
✅ Token management across frameworks
✅ Common mistakes and how to avoid them
✅ Testing patterns

Based on: https://github.com/mapbox/create-web-app

Why this matters:
Now when users ask Claude to "create a React app with Mapbox" or "add Mapbox to my Next.js site", Claude will use official Mapbox patterns from create-web-app, including proper lifecycle management, cleanup to prevent memory leaks, and framework-specific best practices.

This skill complements the existing three:

mapbox-cartography: Design expertise
mapbox-token-security: Security best practices
mapbox-style-patterns: Style configurations
mapbox-integration-patterns: Framework integration ← NEW

PR now has 4 comprehensive skills ready for review! 🚀

Adds comprehensive version guidance section: New "Version Requirements" Section: - Mapbox GL JS: v3.x recommended, v3.0.0 minimum - Framework minimum versions (React 16.8+, Vue 3.x, etc.) - Mapbox Search JS versions - Migration notes for v2.x → v3.x CDN Updates: - Use placeholder "v3.x.x" instead of hardcoded version - Add strong warning: "Prototyping only, not for production" - Explain why CDN is problematic (network dependency, no tree-shaking) - Recommend npm for production: npm install mapbox-gl@^3.0.0 Key Principles: - Use version ranges (^3.0.0) not specific patches (3.15.0) - Document breaking changes between major versions - Explain minimum framework versions for patterns (hooks, etc.) - Guide users toward npm/bundler for production This ensures the skill stays relevant as versions update while providing clear guidance on compatibility requirements. 🤖 Generated with Claude Code

skills/mapbox-integration-patterns/SKILL.md

Fixes based on PR #47 review feedback: 1. Update Angular minimum version - Changed from 15+ to 19+ - Reflects current create-web-app implementation and tutorial - #47 (comment) 2. Remove @mapbox/search-js-core from install instructions - Already included as dependency in search-js-react and search-js-web - Only needed for custom search UI implementations - Removing to reduce noise in skill definition - Added note explaining when -core is needed Changes: - Angular: 19+ minimum (was 15+) - Search JS: Removed redundant -core package from install commands - Added clarifying note about when -core is needed 🤖 Generated with Claude Code

mattpodwysocki · 2025-12-26T17:22:53Z

✅ PR feedback addressed

Fixed both issues from review:

1. Angular version updated

Changed minimum from 15+ to 19+
Now matches create-web-app implementation and tutorial
Ref: [skills] Add Mapbox Agent Skills for domain expertise #47 (comment)

2. Removed @mapbox/search-js-core from install instructions

Already included as dependency in search-js-react and search-js-web
Removed to reduce noise in skill definition
Added note: "Only install -core directly if building custom search UI"

Changes pushed! 🚀

Aligns with create-web-app implementation which targets React 19: https://github.com/mapbox/create-web-app/blob/main/templates/react/package.json Changed from: - Minimum: 16.8+ (requires hooks) - Recommended: 18.x To: - Minimum: 19+ (current implementation in create-web-app) - Recommended: Latest 19.x This matches the Angular 19+ requirement and reflects actual versions used in Mapbox's official scaffolding tool.

ctufts · 2026-01-06T14:13:38Z

skills/mapbox-cartography/SKILL.md

+- See [COLOR_PALETTES.md](COLOR_PALETTES.md) for extended palette library
+- See [TYPOGRAPHY_GUIDE.md](TYPOGRAPHY_GUIDE.md) for advanced typography
+- See [ACCESSIBILITY_CHECKLIST.md](ACCESSIBILITY_CHECKLIST.md) for WCAG compliance


Do these files exist anywhere? It doesn't look like they are checked in.

ctufts · 2026-01-06T14:18:00Z

skills/mapbox-integration-patterns/SKILL.md

+**Example:**
+
+```javascript
+// v2.x pattern (still works in v3.x)
+mapboxgl.accessToken = 'pk...';
+const map = new mapboxgl.Map({ container: '...' });
+
+// v3.x pattern (preferred)
+const map = new mapboxgl.Map({
+  accessToken: 'pk...',
+  container: '...'
+});
+```


This seems conflicting the the Core Principles section in that the token is defined explicitly in the code in both of the above, but imported via env var in the core principles section. Does this need to be consistent?

Sorry, I meant the Framework Specific Patterns section, not Core Principles.

ctufts · 2026-01-06T14:24:52Z

skills/mapbox-integration-patterns/SKILL.md

+| Framework/Bundler    | Environment Variable            | Access Pattern                             |
+| -------------------- | ------------------------------- | ------------------------------------------ |
+| **Vite**             | `VITE_MAPBOX_ACCESS_TOKEN`      | `import.meta.env.VITE_MAPBOX_ACCESS_TOKEN` |
+| **Next.js**          | `NEXT_PUBLIC_MAPBOX_TOKEN`      | `process.env.NEXT_PUBLIC_MAPBOX_TOKEN`     |
+| **Create React App** | `REACT_APP_MAPBOX_TOKEN`        | `process.env.REACT_APP_MAPBOX_TOKEN`       |
+| **Angular**          | `environment.mapboxAccessToken` | Environment files (`environment.ts`)       |


NIT: the react code example seems to utilize the VITE env var, assume it should be changed to be consistent with this table.

ctufts · 2026-01-06T14:33:33Z

skills/mapbox-style-patterns/SKILL.md

+      "id": "buildings",
+      "type": "fill",
+      "source": "mapbox-streets",
+      "source-layer": "building",
+      "paint": {
+        "fill-color": "#1a1a1a",
+        "fill-opacity": 0.8,
+        "fill-outline-color": "#2a2a2a"
+      }
+    },
+    {
+      "id": "roads-minor",
+      "type": "line",
+      "source": "mapbox-streets",
+      "source-layer": "road",
+      "filter": ["in", "class", "street", "street_limited"],
+      "paint": {
+        "line-color": "#2a2a2a",
+        "line-width": {
+          "base": 1.5,
+          "stops": [
+            [12, 0.5],


This is a general comment - how is any of this code (in all of the skills) being verified (both visually and functionally)?

ctufts · 2026-01-06T14:58:22Z

skills/mapbox-token-security/SKILL.md

+- See [SCOPE_REFERENCE.md](SCOPE_REFERENCE.md) for complete scope catalog
+- See [COMPLIANCE_GUIDE.md](COMPLIANCE_GUIDE.md) for regulatory requirements
+- See [INCIDENT_TEMPLATE.md](INCIDENT_TEMPLATE.md) for response procedures


Do these files exist?

…d improve token management consistency

mattpodwysocki · 2026-01-06T21:54:32Z

Re: Code verification question

Good question! Here's how the code in the skills has been verified:

Integration Patterns Skill ():

All patterns are based on Mapbox's official create-web-app scaffolding tool
Code examples were extracted directly from the template files in that repo
This ensures patterns match production-ready implementations maintained by Mapbox

Style Patterns Skill ():

Layer configurations follow Mapbox GL JS style specification
Examples use Mapbox Streets v8 source layers (validated against the resource://mapbox-streets-v8-fields reference in this server)
Style JSON structures can be validated using the style_builder_tool in this MCP server

Cartography & Security Skills:

Content based on Mapbox documentation and best practices
Conceptual guidance rather than executable code

Verification approach:
Since skills are markdown documentation consumed by AI assistants (not executable code), the verification focuses on:

✅ Accuracy of patterns against official sources
✅ Consistency with Mapbox APIs and conventions
✅ Completeness of key concepts and gotchas

For the integration patterns specifically, the connection to create-web-app provides strong validation since that tool generates working apps.

Let me know if you'd like any specific examples tested or validated further!

mattpodwysocki · 2026-01-06T21:54:40Z

Re: Code verification question

Good question! Here's how the code in the skills has been verified:

Integration Patterns Skill:

All patterns are based on Mapbox's official create-web-app scaffolding tool
Code examples were extracted directly from the template files in that repo
This ensures patterns match production-ready implementations maintained by Mapbox

Style Patterns Skill:

Layer configurations follow Mapbox GL JS style specification
Examples use Mapbox Streets v8 source layers (validated against the resource in this server)
Style JSON structures can be validated using the style_builder_tool in this MCP server

Cartography & Security Skills:

Content based on Mapbox documentation and best practices
Conceptual guidance rather than executable code

Verification approach:
Since skills are markdown documentation consumed by AI assistants (not executable code), the verification focuses on:

Accuracy of patterns against official sources
Consistency with Mapbox APIs and conventions
Completeness of key concepts and gotchas

For the integration patterns specifically, the connection to create-web-app provides strong validation since that tool generates working apps.

Let me know if you'd like any specific examples tested or validated further!

mattpodwysocki requested a review from a team as a code owner December 19, 2025 06:36

Merge main into add-agent-skills to resolve README conflict

1c28536

- Resolved conflict by including both Agent Skills and Prompts sections - Agent Skills section appears first, followed by Prompts section - All prompts from main are now included in this branch

AndrewSepic reviewed Dec 23, 2025

View reviewed changes

skills/mapbox-integration-patterns/SKILL.md Outdated Show resolved Hide resolved

AndrewSepic reviewed Dec 23, 2025

View reviewed changes

skills/mapbox-integration-patterns/SKILL.md Outdated Show resolved Hide resolved

mattpodwysocki requested a review from AndrewSepic December 26, 2025 17:24

mattpodwysocki added 2 commits December 26, 2025 12:43

[skills] Update Svelte minimum version to 5+

ba33a12

ctufts reviewed Jan 6, 2026

View reviewed changes

[skills] Address PR feedback - remove non-existent file references an…

eb4c210

…d improve token management consistency

ctufts approved these changes Jan 6, 2026

View reviewed changes

mattpodwysocki merged commit e279a15 into main Jan 6, 2026
1 check passed

[skills] Add Mapbox Agent Skills for domain expertise #47

[skills] Add Mapbox Agent Skills for domain expertise #47

Conversation

mattpodwysocki commented Dec 19, 2025

Summary

New Skills

🎨 mapbox-cartography (~300 lines)

🔐 mapbox-token-security (~490 lines)

📐 mapbox-style-patterns (~800 lines)

Documentation

File Structure

Usage Example

Relationship to Other PRs

Testing

Uh oh!

mattpodwysocki commented Dec 19, 2025

Uh oh!

mattpodwysocki commented Dec 19, 2025

🔧 mapbox-integration-patterns

Uh oh!

Uh oh!

Uh oh!

mattpodwysocki commented Dec 26, 2025

Uh oh!

ctufts Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctufts Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctufts Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctufts Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctufts Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

ctufts Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

mattpodwysocki commented Jan 6, 2026

Uh oh!

mattpodwysocki commented Jan 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants