[skills] Add Mapbox Agent Skills for domain expertise

[mattpodwysocki]

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:

1. [mapbox-cartography] Understand that restaurant maps need high-contrast markers, muted backgrounds, clear navigation labels
2. [mapbox-token-security] Create tokens with proper scopes and URL restrictions
3. [mapbox-style-patterns] Apply the POI Finder pattern with proven configurations
4. [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

[mattpodwysocki]

✅ 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.

[mattpodwysocki]

✨ 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! 🚀

[AndrewSepic]

Our angular implementation (in create-web-app) & tutorial are based on Angular 19+

[AndrewSepic]

I'm not exactly sure what the context here is, but @mapbox/search-js-core dependency is included in the first 2 (web & reac) and is generally only needed if you want to build your own custom UI around the core search classes.

Not sure if it's beneficial to include this, based on the context, or if it will cause 'noise' in the skill definition.

[mattpodwysocki]

✅ 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! 🚀