This document explains the relationship between MCP Prompts and Agent Skills in the Mapbox MCP DevKit Server.
Prompts provide step-by-step workflows (orchestration) Skills provide domain expertise (knowledge) Tools provide capabilities (actions)
They're complementary features that work together but are technically independent.
Prompts are MCP server features that provide step-by-step instructions:
User → Invokes prompt → MCP Server returns instructions → Claude follows them
When invoked, the MCP server returns structured instructions:
Step 1: Use create_token_tool with these parameters...
Step 2: Use create_style_tool...
Step 3: Use preview_style_tool...
Claude follows these instructions mechanically with only the knowledge embedded in the prompt text.
The prompt tells Claude WHAT to do, but Claude lacks deeper understanding of:
- WHY certain approaches are better
- Design trade-offs and best practices
- Domain-specific considerations
Skills are NOT part of the MCP server - they're markdown files that Claude Code/API/Claude.ai reads directly:
User asks question
↓
Claude has access to:
1. MCP Tools (capabilities: create_style_tool, list_tokens_tool)
2. MCP Prompts (workflows: setup-mapbox-project, debug-mapbox-integration)
3. Agent Skills (expertise: map design principles, security best practices)
↓
Claude makes informed decisions
Scenario: User says "Create a map for my restaurant app"
User → Claude looks at available prompts → Uses "create-and-preview-style"
Claude's behavior:
- Creates a basic style
- Uses default colors
- Creates a token with required scopes
- ❌ No explanation of design choices
- ❌ No awareness of restaurant-specific needs
User → Claude considers:
- [mapbox-cartography skill]
"Restaurant maps need high-contrast markers, muted backgrounds
so food photos stand out, clear street labels for navigation"
- [mapbox-token-security skill]
"Use public token with URL restrictions for client-side apps"
- [mapbox-style-patterns skill]
"Apply POI Finder pattern: desaturated base, orange markers (#FF6B35)"
Claude then:
- Uses
style_builder_toolwith context: "Create a restaurant-optimized map with muted background" - Creates token with proper URL restrictions
- Applies POI Finder pattern recommendations
- ✅ Explains design decisions to user
- ✅ Provides best practices for the use case
| Aspect | Before Skills | After Skills |
|---|---|---|
| Where they live | MCP server (TypeScript code) | Filesystem (Markdown files) |
| How they're invoked | User explicitly calls prompt | Claude automatically uses relevant skills when needed |
| What they provide | Step-by-step workflow instructions | Domain expertise, design principles, best practices |
| Prompt behavior | Returns same instructions | Returns same instructions, but Claude understands context better |
| Decision quality | Follows instructions literally | Makes informed, context-aware decisions |
| User experience | "Do these steps" | "Do these steps well, and here's why" |
// src/prompts/SetupMapboxProjectPrompt.ts
export class SetupMapboxProjectPrompt extends BasePrompt {
readonly name = 'setup-mapbox-project';
getMessages(args: Record<string, string>): PromptMessage[] {
return [{
role: 'user',
content: {
type: 'text',
text: `
Step 1: Use create_token_tool with...
Step 2: Use create_style_tool with...
`
}
}];
}
}How it works:
- User invokes prompt via MCP protocol
- Server executes
getMessages()method - Returns structured instructions to Claude
- Claude follows the instructions
<!-- skills/mapbox-token-security/SKILL.md -->
---
name: mapbox-token-security
description: Security best practices for Mapbox access tokens
---
# Mapbox Token Security Skill
## Token Types and When to Use Them
### Public Tokens (pk.*)
- Can be safely exposed in client-side code
- Limited to specific public scopes only
- **Must have URL restrictions**
### Secret Tokens (sk.*)
- **NEVER expose in client-side code**
- Store in environment variables
- Use for server-side operations onlyHow it works:
- Claude Code/API loads skills from filesystem or Skills API
- Skills are available as context when Claude thinks
- Claude automatically applies relevant knowledge
- No explicit invocation needed
- They return identical instruction messages
- The MCP server doesn't know about skills
- Skills don't modify prompt behavior
- You can use prompts without skills
- Claude can choose better parameters when invoking tools
- Claude can explain decisions using skill knowledge
- Claude can adapt prompt instructions based on context
- Better recommendations and error handling
┌─────────────────────────────────────────────────────────┐
│ User Request │
│ "Create a map for my restaurant app" │
└────────────────────┬────────────────────────────────────┘
│
▼
┌───────────────────────────────────────┐
│ Claude (AI Assistant) │
│ │
│ Considers all available context: │
│ ┌─────────────────────────────────┐ │
│ │ Agent Skills (Domain Expertise) │ │
│ │ • Map design principles │ │
│ │ • Security best practices │ │
│ │ • Common patterns │ │
│ └─────────────────────────────────┘ │
│ │
│ Makes informed decision to use: │
│ ┌─────────────────────────────────┐ │
│ │ MCP Prompts (Workflows) │ │
│ │ • setup-mapbox-project │ │
│ │ • create-and-preview-style │ │
│ └─────────────────────────────────┘ │
│ │
│ Which orchestrates calls to: │
│ ┌─────────────────────────────────┐ │
│ │ MCP Tools (Actions) │ │
│ │ • create_token_tool │ │
│ │ • style_builder_tool │ │
│ │ • create_style_tool │ │
│ └─────────────────────────────────┘ │
└───────────────────────────────────────┘
│
▼
┌────────────────┐
│ Mapbox API │
└────────────────┘
1. User: "I'm getting 401 errors"
2. Claude: Uses debug-mapbox-integration prompt
3. Prompt says: "Check token validity with list_tokens_tool"
4. Claude: Runs list_tokens_tool
5. Claude: "Your token exists. Try checking the scopes."
❌ Generic advice, no specific guidance
1. User: "I'm getting 401 errors"
2. Claude: Uses debug-mapbox-integration prompt + token-security skill
3. Skill teaches: "401 typically means: invalid token, missing scopes,
or token not set correctly"
4. Claude: Runs list_tokens_tool
5. Claude: "I see your token has styles:list scope but you're trying
to create a style, which needs styles:write. Here's how to add it..."
✅ Specific diagnosis and actionable solution
| Component | Type | Purpose | Example |
|---|---|---|---|
| MCP Tools | Execute | Perform actions | create_style_tool - creates a style |
| MCP Prompts | Orchestrate | Multi-step workflows | setup-mapbox-project - guides through project setup |
| Agent Skills | Educate | Domain expertise | mapbox-cartography - teaches map design principles |
- Use Tools when you need to perform a single action
- Use Prompts when you need to complete a multi-step workflow
- Use Skills when Claude needs domain expertise to make better decisions
Before: Prompts = "Do these steps" After: Prompts = "Do these steps" + Skills = "Here's why and how to do them well"
Skills make Claude a better domain expert, while prompts remain efficient workflow orchestrators.
src/prompts/
├── BasePrompt.ts
├── CreateAndPreviewStylePrompt.ts
├── SetupMapboxProjectPrompt.ts
├── DebugMapboxIntegrationPrompt.ts
└── promptRegistry.ts
skills/
├── mapbox-cartography/
│ └── SKILL.md
├── mapbox-token-security/
│ └── SKILL.md
└── mapbox-style-patterns/
└── SKILL.md
src/tools/
├── create-style-tool/
├── create-token-tool/
├── style-builder-tool/
└── [20+ other tools]
- Agent Skills Specification: https://agentskills.io
- MCP Documentation: https://modelcontextprotocol.io
- Mapbox MCP DevKit Server: https://github.com/mapbox/mcp-devkit-server
Created for the Mapbox Location AI team to explain the relationship between MCP Prompts and Agent Skills