Skill: ivangdavila/maps (version 1.0.0)

--- name: Maps slug: maps version: 1.0.0 homepage: https://clawic.com/skills/maps description: Plan place search, geocoding, routing, and map-link workflows across Google Maps, Apple Maps, OpenStreetMap, and other providers. changelog: Initial release with provider selection rules, normalized map workflows, and safer route and link execution patterns. metadata: {"clawdbot":{"emoji":"MAP","requires":{"bins":[],"config":["~/maps/"]},"os":["linux","darwin","win32"],"configPaths":["~/maps/"]}} --- ## When to Use User needs place search, forward geocoding, reverse geocoding, routing, travel-time estimates, static map links, or provider selection for a maps workflow. Use this skill when the agent must move between Google Maps, Apple Maps, OpenStreetMap, Mapbox, or another provider without mixing schemas, wasting quota, or opening the wrong route. ## Architecture Memory lives in `~/maps/`. If `~/maps/` does not exist, run `setup.md`. See `memory-template.md` for structure. ```text ~/maps/ |-- memory.md # Activation rules, provider defaults, and privacy/cost boundaries |-- provider-notes.md # Known provider quirks, quota notes, and verified workarounds |-- recurring-places.md # User-approved recurring origins, destinations, and map contexts `-- run-log.md # Optional notes on failures, ambiguous matches, and fixes ``` ## Quick Reference Load only the file needed for the current map task. | Topic | File | |-------|------| | Setup and activation behavior | `setup.md` | | Memory schema and status model | `memory-template.md` | | Provider choice by task and constraint | `provider-matrix.md` | | Canonical schema and coordinate normalization | `normalization-guide.md` | | Search, route, and launch workflows | `execution-patterns.md` | | Cost controls and fallback logic | `cost-controls.md` | | Common failures and recovery steps | `troubleshooting.md` | ## Requirements - No credentials required for provider selection, normalization, and map-link planning. - Live Google Maps, Mapbox, HERE, or other paid API calls need user-approved credentials. - Apple Maps app launching is macOS-specific, but Apple Maps link generation works anywhere a browser can open `https://maps.apple.com`. - Confirm before sending sensitive origin, destination, or itinerary data to a live provider. ## Coverage This skill is designed for mixed map work that usually fails when an agent treats every provider as interchangeable: - place search and place-detail workflows - forward and reverse geocoding - route and matrix calculations - static map or shareable map-link generation - provider fallback when quota, privacy, or coverage changes the right choice ## Core Rules ### 1. Separate structured data from launch actions - Decide first whether the user wants machine-readable output, an interactive map, or both. - Use APIs for structured records and calculations. - Use app or browser links only when the user wants to open, preview, or share a map. ### 2. Normalize every provider before comparing results - Keep coordinates internally as decimal `lat` and `lng`, then serialize per provider. - Track result type, confidence, place status, provider ID, timezone, and distance units before merging outputs. - Use `normalization-guide.md` whenever provider schemas disagree. ### 3. Bound ambiguous searches with context and confidence - Add city, region, postal code, country, or nearby coordinates before calling search or geocode endpoints. - If top candidates disagree on locality or type, ask a disambiguation question instead of guessing. - Do not treat the first geocode result as truth when the provider reports approximate or partial matches. ### 4. Route travel distance through a route engine - Haversine is only for radius filters, rough proximity checks, and clustering. - For ETA, driving distance, cycling, transit, or waypoint order, use a routing or matrix engine. - Explicitly set travel mode and units before comparing providers. ### 5. Choose the provider by task, cost, and privacy - Use `provider-matrix.md` to pick the cheapest provider that still meets the accuracy and policy needs of the task. - Default to Apple Maps for app-launch workflows, Google for broad place detail coverage, and the OpenStreetMap stack for low-cost open-data fallback. - Switch providers only when the delta is clear: richer data, safer privacy posture, better coverage, or lower cost. ### 6. Preview high-impact executions - Show final route mode, origin, destination, and provider before opening routes or sharing links. - For multiple links, repeated launches, or route changes, require explicit confirmation. - If a link contains private notes or sensitive addresses, confirm again before execution. ### 7. Degrade gracefully when providers fail - Fall back from premium APIs to open-data providers when the result quality remains acceptable. - Cache canonicalized queries and provider IDs so repeated geocodes do not burn quota. - If no trustworthy fallback exists, stop and explain whether the blocker is quota, precision, coverage, or privacy. ## Common Traps - Swapping `lat,lng` and `lng,lat` -> routes jump continents or geofences miss targets. - Truncating coordinates below 5-6 decimals -> rooftop and curbside results drift by tens to hundreds of meters. - Treating the first geocode result as final -> duplicate street names and chain locations cause silent errors. - Using straight-line distance for delivery or commute promises -> travel times can be off by 2-5x. - Mixing launch URLs with API schemas -> a valid Apple Maps link does not imply a complete structured place record. - Ignoring place status and confidence -> closed businesses and approximate addresses leak into downstream logic. - Repeating the same paid lookup -> avoidable quota burn and inconsistent results when provider ordering changes. ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | https://maps.googleapis.com | addresses, coordinates, place queries, route parameters | Google geocoding, places, routes, and static maps | | https://maps.apple.com | search text, coordinates, and route parameters | Apple Maps links and app or browser launch | | https://nominatim.openstreetmap.org | address text or reverse-geocode coordinates | OpenStreetMap geocoding fallback | | https://router.project-osrm.org | coordinates and route mode | Open-source route estimates when supported | | https://api.mapbox.com | queries, coordinates, and route parameters | Alternative geocoding, routing, and static maps | No other data should be sent externally unless the user approves another provider. ## Security & Privacy Data that may leave your machine: - address queries - coordinates - route origin and destination - place-search text - optional static-map parameters Data that stays local: - notes in `~/maps/` - provider preferences and fallback rules - user-approved recurring contexts - failure logs and verified fixes This skill does NOT: - store API keys in local notes - guess precise destinations from vague requests - treat a launch URL as proof of data accuracy - modify its own `SKILL.md` ## Trust This skill can send addresses, coordinates, and route parameters to the map provider selected for the task. Only use live provider calls or link launches if you trust that provider with the relevant location data. ## Scope This skill ONLY: - selects providers and execution modes for map work - normalizes place, geocode, route, and link workflows - prepares safe request plans, links, or structured summaries This skill NEVER: - invent place data, ETAs, or coverage claims - scrape undeclared providers behind anti-bot flows - share map links externally without approval - persist sensitive location history without telling the user first ## Related Skills Install with `clawhub install <slug>` if user confirms: - `apple-maps` - Open Apple Maps search and route flows on macOS with local command automation. - `travel` - Turn approved routes, places, and movement constraints into broader trip plans. - `tripadvisor` - Add venue comparison and official travel-data workflows to place shortlists. - `car-rental` - Connect route assumptions, pickup zones, and transport choices to rental planning. ## Feedback - If useful: `clawhub star maps` - Stay updated: `clawhub sync`

path: cost-controls.md
content: # Cost Controls - Maps

Use these rules before sending live map requests.

## Query Hygiene

- Canonicalize address strings before geocoding so the same address is not billed twice.
- Reuse provider IDs once a place is confirmed instead of re-searching by free text.
- Keep place search bounded to the smallest useful area.

## Provider Escalation

- Start with the cheapest provider that can meet the precision requirement.
- Escalate to premium providers only when the task needs richer metadata, stronger confidence, or traffic-aware routing.
- Do not use premium routing for rough radius checks or brainstorming.

## Batch Discipline

- Prefer matrix endpoints over many single-route calls only when pair counts justify it.
- Cache recurring origins and destinations locally after user approval.
- Rate-limit retries and exponential backoff on quota or transient failure responses.

## Quota Red Flags

- repeated geocoding of the same address
- route recalculation after each wording tweak
- broad nearby searches without area bias
- static-map regeneration when only labels changed

If any red flag appears, stop and simplify before sending more requests.


path: execution-patterns.md
content: # Execution Patterns - Maps

Use these patterns to keep map behavior deterministic and reviewable.

## Place Search Pattern

1. Confirm the search text and missing geography context.
2. Pick provider based on detail needs, cost, and privacy.
3. Search for a small bounded result set.
4. Compare top candidates by locality, type, and status.
5. Open or share only after the user approves the right candidate.

## Forward Geocoding Pattern

1. Expand the address with city, region, postal code, and country when available.
2. Request provider output and capture confidence or match type.
3. Return normalized coordinates plus the formatted address.
4. If the result is approximate, say so explicitly.

## Reverse Geocoding Pattern

1. Preserve full input precision.
2. Call a provider that reports confidence or granularity.
3. Return the nearest address plus locality context.
4. Warn if the match is approximate or snapped to a road segment.

## Route Pattern

1. Confirm origin, destination, travel mode, and unit expectations.
2. Decide whether the user needs a structured result, an open map, or both.
3. Use a route engine for ETA and actual distance.
4. Preview final provider, route mode, and major assumptions before launch.

## Matrix or Multi-Stop Pattern

1. Deduplicate repeated origins or destinations before calling the API.
2. Use matrix endpoints only when pair counts justify them.
3. Record returned waypoint order and unit assumptions.
4. If the provider cannot optimize waypoints, say so before computing a fake answer.

## Map Link or App Launch Pattern

1. Build the final URL after the correct place or route is chosen.
2. Show the provider, route mode, and sensitive fields before execution.
3. Require explicit confirmation for share links, bulk opens, or route changes.
4. Summarize the expected visible result after launch.


path: memory-template.md
content: # Memory Template - Maps

Create `~/maps/memory.md` with this structure:

```markdown
# Maps Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending | done | declined

## Activation Preferences
<!-- Always-on, explicit-only, or keyword-based activation rules -->

## Provider Defaults
<!-- Preferred providers for search, geocoding, routing, and link launching -->

## Geography Defaults
<!-- Typical cities, countries, units, language bias, and time formatting -->

## Privacy and Cost Boundaries
<!-- What providers to avoid, when to ask before live calls, and paid-call limits -->

## Recurring Context
<!-- User-approved recurring origins, destinations, and map contexts -->

## Failure Patterns
<!-- Ambiguous results, provider-specific bugs, and the recovery that worked -->

## Notes
<!-- Short context that improves the next map workflow -->

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Context is still evolving | Ask only when missing details change correctness, privacy, or cost |
| `complete` | Stable map defaults exist | Prioritize execution and targeted clarification |
| `paused` | User paused setup | Keep current defaults and avoid new setup prompts |
| `never_ask` | User does not want setup prompts | Use only explicit instructions unless safety requires clarification |

## Key Principles

- Keep memory in natural language, not raw request dumps.
- Store only context that improves provider choice, accuracy, privacy, or cost.
- Update `last` after meaningful changes to provider defaults or recurring map contexts.
- Preserve recurring failure patterns because they prevent repeat geography mistakes.
- Never persist API keys, private itineraries, or sensitive location history by default.


path: normalization-guide.md
content: # Normalization Guide - Maps

Normalize provider output before merging, ranking, or caching it.

## Canonical Coordinate Model

Keep coordinates internally as:

```text
lat: decimal degrees
lng: decimal degrees
precision: rooftop | range_interpolated | approximate | centroid | unknown
```

Preserve at least 6 decimal places when the provider offers them.

## Canonical Place Record

Use this minimum record shape:

```text
provider
provider_id
label
formatted_address
lat
lng
confidence
precision
status
types[]
timezone
source_url
```

## Provider Serialization Differences

| Provider or format | Coordinate order | Notes |
|--------------------|------------------|-------|
| Google Maps APIs | `lat,lng` | Human-readable order in most docs and URLs |
| Apple Maps links | `lat,lng` or text query plus optional `ll` | Best for opening or sharing, not for rich place IDs |
| GeoJSON | `[lng, lat]` | Common source of inverted points |
| Mapbox APIs | `[lng, lat]` in many payloads | Do not reuse Google serialization blindly |
| OSRM | `lng,lat` in path segments | Keep conversion explicit at request boundaries |

## Confidence Rules

- `rooftop` or exact parcel match -> safe for navigation and delivery-style precision
- `range_interpolated` -> good for address vicinity, not for exact entrance claims
- `approximate` or locality-level -> safe for area search only
- mixed-provider disagreement -> ask a clarification question or show top candidates

## Route Normalization

For every route or matrix result, normalize:
- provider
- travel mode
- distance meters
- duration seconds
- traffic included yes or no
- tolls or restrictions stated yes or no
- waypoint order returned yes or no

Never compare route outputs until units and traffic assumptions match.


path: provider-matrix.md
content: # Provider Matrix - Maps

Use this matrix to choose the first provider instead of defaulting blindly.

| Task | Start here | Switch when | Why |
|------|------------|-------------|-----|
| Open a map or route for the user | Apple Maps or Google Maps link | Platform mismatch or user preference | Launch workflows are about UX, not structured data richness |
| Rich place search and business details | Google Maps | Paid quota is not acceptable or coverage is weak | Google usually has the richest place metadata |
| Forward geocoding at low cost | Nominatim or other OSM stack | Need stronger rooftop confidence or stricter SLA | Open data is cheap but precision varies |
| Reverse geocoding | Google Maps or Mapbox | Only coarse locality is needed | Reverse geocoding quality varies more than forward geocoding |
| Route ETA and waypoint optimization | Google Routes or Mapbox Directions | Budget is tight and rough estimates are acceptable | Premium routing usually wins on richer mode and traffic support |
| Distance matrix or many OD pairs | Google Matrix or Mapbox Matrix | Budget is tight or traffic is not needed | Matrix calls are where quota can explode fastest |
| Static map image or shareable preview | Google Static Maps or Mapbox Static | Link-only output is enough | Static map APIs need stricter URL and marker limits |
| Open-data fallback | Nominatim plus OSRM | Coverage or SLA is insufficient | Good fallback when paid providers are blocked or unnecessary |

## Provider Deltas

### Google Maps
- Best for: place richness, broad coverage, route features, business metadata
- Watch for: quota burn, paid usage, multiple APIs with different limits

### Apple Maps
- Best for: opening maps for humans, route launch on Apple devices, lightweight share links
- Watch for: app-launch workflows are not the same as structured API records

### OpenStreetMap Stack
- Best for: low-cost geocoding fallback, open data, and transparent map data
- Watch for: stricter usage policies, weaker place detail consistency, less polished route metadata

### Mapbox
- Best for: developer-facing geocoding, routing, and static map APIs with strong docs
- Watch for: GeoJSON-style coordinate ordering and token-scoped limits

### HERE or Other Providers
- Best for: enterprise contracts, regional coverage, or a user-mandated stack
- Watch for: schema drift, custom auth rules, and provider-specific licensing constraints


path: setup.md
content: # Setup - Maps

Use this file when `~/maps/` is missing or empty.
Keep onboarding short and centered on the real map task in front of you.

## Operating Posture

Be precise, provider-neutral, and privacy-aware.
Optimize for correct geography first, then cost, then convenience.

## Early Alignment

In the first exchanges, establish:
- activation preference: always on for place, route, geocode, and map-link tasks or explicit request only
- execution boundary: planning only, copy-paste API requests, live provider calls after confirmation, or app-link launch when helpful
- provider preference: richer proprietary data, open-data fallback, Apple-first app launching, or cheapest acceptable result
- locale defaults: miles vs kilometers, 12-hour vs 24-hour time, and preferred place-language bias

Store only the minimum reusable context that makes the next map task faster and safer.

## How to Start Work

Classify the task before asking for details:
- place search
- forward geocoding
- reverse geocoding
- route or ETA
- matrix or waypoint optimization
- static map or share link

Ask only for context that changes correctness:
- city, neighborhood, country, or coordinates
- origin and destination
- travel mode
- whether the user wants structured data, an open map, or both

Separate rough proximity from actual route questions immediately.
If the user shares recurring home, office, or travel hubs, ask whether local notes are acceptable before storing them.

## Personalization Rules

Adapt to the task shape:
- developers and operators: prioritize schema normalization, cost, and request determinism
- travel planners: prioritize route clarity, venue disambiguation, and shareable links
- local discovery: prioritize status checks, neighborhood context, and opening only the most relevant map
- logistics work: prioritize matrix calculations, recurring origins, and clear fallback paths

Use natural language and avoid long API-history lectures unless requested.

## Internal Notes Policy

Maintain concise records in `memory.md`:
- activation and execution preferences
- provider defaults and no-go providers
- units, locale, and recurring geography context
- privacy and cost boundaries
- repeated failure patterns and the fix that worked

Do not store API keys, raw itinerary dumps, or sensitive location history by default.

## Setup Completion

Setup is sufficient when activation preference, execution boundary, provider bias, and locale defaults are clear enough to help immediately.
Continue with the real map task and refine context through use.


path: troubleshooting.md
content: # Troubleshooting - Maps

## Result Is in the Wrong Place

Symptoms:
- The returned point is in the wrong city or country.

Actions:
1. Check coordinate order and serialization.
2. Add explicit city, region, postal code, or country bias.
3. Re-run with a bounded query instead of free text alone.

## Address Match Is Too Fuzzy

Symptoms:
- Provider returns locality-level or approximate matches only.

Actions:
1. Ask for missing apartment, postal code, or district context.
2. Switch to a provider with stronger rooftop geocoding if needed.
3. Mark the result as approximate instead of pretending it is exact.

## Travel Time Looks Unrealistic

Symptoms:
- ETA or distance is much lower than expected.

Actions:
1. Confirm the route used a real routing engine, not Haversine.
2. Verify travel mode and traffic assumptions.
3. Re-check whether ferries, tolls, or highways were implicitly included.

## Apple Maps Link Opens in Browser Instead of the App

Symptoms:
- The link opens in a browser tab on macOS instead of Maps.app.

Actions:
1. Keep the link for sharing.
2. If local execution matters, use a macOS-specific `open -a Maps` workflow.
3. Treat the browser-open result as a launch-path issue, not a data issue.

## Paid Provider Returns Quota Errors

Symptoms:
- Provider reports limit, denied, or rate errors.

Actions:
1. Stop repeating the same request.
2. Switch to cached results or an acceptable fallback provider.
3. Document whether the blocker is daily quota, bad auth, or burst rate.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)