Mapbox
Use this skill for practical Mapbox platform work in web apps and API integrations.
Workflow
- 1. Confirm the runtime first: plain HTML, Vite, React, Next.js, or another framework.
- Confirm which Mapbox surface is involved: GL JS map rendering, styles, tilesets, geocoding, directions, or static images.
- Start with the smallest working map before adding custom sources, layers, controls, or API calls.
- Keep access tokens out of source files and examples unless the user explicitly wants a local-only demo.
- For bugs, isolate whether the failure is in container sizing, token/scopes, style/source IDs, coordinate order, or layer order.
Implementation Guardrails
- - Prefer
mapbox-gl with explicit imports and explicit CSS loading. - Always ensure the map container has a real height before debugging rendering.
- Use
lng, lat order consistently for Mapbox coordinate arrays. - Add sources before layers, and keep layer IDs stable so updates are easy.
- Prefer GeoJSON for lightweight overlays; move to vector tiles or tilesets for larger datasets.
- In React or other SPA frameworks, remove the map instance during teardown to avoid leaks.
- Treat the access token as configuration. Read it from environment or runtime config instead of hardcoding it.
Common Failure Checks
- - Blank map: verify token, style URL, CSS import, and container height.
- Layer not visible: verify source exists, source-layer matches, zoom bounds, and paint/layout visibility.
- Wrong location: verify coordinate order and CRS assumptions; Mapbox expects WGS84
lng,lat. - Performance issues: reduce marker count, cluster point data, and prefer data-driven layers over many DOM markers.
- API failures: verify token scopes, endpoint type, rate limits, and request parameters.
Task Boundaries
- - Use this skill for Mapbox-specific implementation, debugging, and integration patterns.
- For generic CRS/projection reasoning, use
project or wgs84. - For deterministic desktop GIS batch processing, use
qgis. - For CesiumJS globe rendering, use
cesium.
OpenClaw + ClawHub Notes
- - Keep examples generic, portable, and token-safe.
- Do not hardcode private datasets, private style URLs, or machine-specific paths.
- For clawhub.ai publication, keep content reproducible and semver-friendly; put detailed examples in references instead of bloating
SKILL.md.
Reference Docs In This Skill
- - Read
{baseDir}/references/patterns.md when generating or fixing Mapbox GL JS or API integration code.
Mapbox
使用此技能进行Web应用和API集成中的实际Mapbox平台工作。
工作流程
- 1. 首先确认运行时环境：纯HTML、Vite、React、Next.js或其他框架。
- 确认涉及的Mapbox层面：GL JS地图渲染、样式、瓦片集、地理编码、导航或静态图像。
- 在添加自定义数据源、图层、控件或API调用之前，先从最小可运行的地图开始。
- 除非用户明确需要仅限本地的演示，否则将访问令牌保留在源文件和示例之外。
- 对于错误，隔离故障原因：容器尺寸、令牌/作用域、样式/数据源ID、坐标顺序或图层顺序。
实施规范
- - 优先使用带显式导入和显式CSS加载的mapbox-gl。
- 在调试渲染之前，始终确保地图容器具有实际高度。
- 对于Mapbox坐标数组，始终一致使用经度, 纬度顺序。
- 先添加数据源再添加图层，并保持图层ID稳定以便于更新。
- 轻量级叠加层优先使用GeoJSON；大数据集则迁移到矢量瓦片或瓦片集。
- 在React或其他SPA框架中，在销毁时移除地图实例以避免内存泄漏。
- 将访问令牌视为配置项。从环境变量或运行时配置中读取，而非硬编码。
常见故障排查
- - 地图空白：检查令牌、样式URL、CSS导入和容器高度。
- 图层不可见：检查数据源是否存在、源图层是否匹配、缩放范围以及绘制/布局可见性。
- 位置错误：检查坐标顺序和CRS假设；Mapbox期望WGS84的经度,纬度格式。
- 性能问题：减少标记数量、对点数据进行聚类，优先使用数据驱动图层而非大量DOM标记。
- API失败：检查令牌作用域、端点类型、速率限制和请求参数。
任务边界
- - 使用此技能处理Mapbox特定的实现、调试和集成模式。
- 对于通用的CRS/投影推理，使用project或wgs84。
- 对于确定性的桌面GIS批处理，使用qgis。
- 对于CesiumJS地球渲染，使用cesium。
OpenClaw + ClawHub 说明
- - 保持示例通用、可移植且令牌安全。
- 不要硬编码私有数据集、私有样式URL或特定机器的路径。
- 对于clawhub.ai发布，保持内容可复现且语义化版本友好；将详细示例放在参考资料中，避免使SKILL.md过于臃肿。
本技能中的参考文档
- - 在生成或修复Mapbox GL JS或API集成代码时，请阅读{baseDir}/references/patterns.md。
