Setup
On first use, follow setup.md to establish scope, preferred command path, and safety defaults before routing or sharing actions.
When to Use
User wants to search places, categories, addresses, and routes in Apple Maps from macOS without browser-first workflows.
Agent handles place search, nearby category lookup, route launching, and reusable map-link generation.
Requirements
- macOS with Maps.app installed.
- At least one working command path:
open, shortcuts, or osascript fallback.
- Network access to Apple Maps for live place and route results.
- Explicit confirmation before sharing links externally or launching bulk actions.
Architecture
Memory lives in ~/apple-maps/. See memory-template.md for structure.
~/apple-maps/
├── memory.md # Status, defaults, and validated command path
├── command-paths.md # Command priority, probes, and URL strategy
├── safety-log.md # Confirmations for high-impact actions
└── operation-log.md # Search and route operation IDs with outcomes
Quick Reference
| Topic |
File |
| Setup and first-run behavior |
setup.md |
| Memory structure |
memory-template.md |
| Command hierarchy and probes |
command-paths.md |
| Deterministic operation flows |
operation-patterns.md |
| Safety checklist before action |
safety-checklist.md |
| Failure handling and recovery |
troubleshooting.md |
Data Storage
All skill files are stored in ~/apple-maps/.
Before creating or changing local files, describe the planned write and ask for confirmation.
Core Rules
1. Use Apple Maps URL Workflows as Primary Interface
- Build map requests as explicit Apple Maps URLs and launch with
open -a Maps.
- Prefer documented URL parameters instead of UI-only automation.
2. Probe Command Path Before Operations
- Verify command availability in strict order:
open, shortcuts, osascript.
- If only fallback paths are available, explain capability limits before executing.
3. Keep Searches Bounded and Deterministic
- Require clear intent: query text, optional area, and optional map zoom/context.
- For ambiguous requests like "best restaurants", ask for location context before launching Maps.
4. Preview Generated URL Before Execution
- For every action, show the final URL and explain major parameters.
- If the query contains user-sensitive text, confirm before opening or sharing.
5. Confirm High-Impact Actions
- Require explicit confirmation for route launches with destination changes, share-link generation, and repeated bulk opens.
- For repeated actions, present a count and require a second confirmation.
6. Verify Result State After Launch
- After opening Maps, summarize expected visible outcome (query, destination, mode).
- If result does not match intent, refine parameters instead of retrying blindly.
7. Minimize Data Exposure
- Use minimal query strings needed for the requested task.
- Do not send map queries to undeclared third-party APIs.
Common Traps
- Launching vague searches without area context -> noisy, low-value results.
- Sharing raw links that include private notes -> accidental disclosure.
- Using UI scripting as default path -> brittle behavior across locales.
- Opening many candidate links at once -> user loses context quickly.
- Assuming route mode without confirmation -> wrong transport directions.
External Endpoints
| Endpoint |
Data Sent |
Purpose |
| https://maps.apple.com |
Search text, optional coordinates, routing parameters |
Retrieve map, place, and route results in Apple Maps |
No other external endpoint is required by default.
Security & Privacy
Data that stays local:
- Operational defaults, safety choices, and command reliability notes in
~/apple-maps/.
Data that may leave your machine:
- Place queries, route origins/destinations, and map parameters sent to Apple Maps when opening URLs.
This skill does NOT:
- Execute undeclared API calls.
- Persist sensitive location context without user approval.
- Run bulk opens or share actions without explicit confirmation.
Trust
By using this skill, map queries and route parameters are sent to Apple Maps.
Only use this workflow if you trust Apple Maps with that data.
Related Skills
Install with clawhub install <slug> if user confirms:
macos - macOS command workflows and automation patterns.travel - travel-planning flows and destination strategy.restaurants - food venue discovery and shortlist workflows.car-rental - route-linked transport planning.
Feedback
- If useful:
clawhub star apple-maps
- Stay updated:
clawhub sync
1---2name: apple-maps-macos3description: Search places, open routes, and run Apple Maps workflows on macOS using local CLI commands and shortcut automation with explicit safety checks.4---5
6## Setup
7
8On first use, follow `setup.md` to establish scope, preferred command path, and safety defaults before routing or sharing actions.
9
10## When to Use
11
12User wants to search places, categories, addresses, and routes in Apple Maps from macOS without browser-first workflows.
13Agent handles place search, nearby category lookup, route launching, and reusable map-link generation.
14
15## Requirements
16
17- macOS with Maps.app installed.
18- At least one working command path: `open`, `shortcuts`, or `osascript` fallback.
19- Network access to Apple Maps for live place and route results.
20- Explicit confirmation before sharing links externally or launching bulk actions.
21
22## Architecture
23
24Memory lives in `~/apple-maps/`. See `memory-template.md` for structure.
25
26```text
27~/apple-maps/
28├── memory.md # Status, defaults, and validated command path
29├── command-paths.md # Command priority, probes, and URL strategy
30├── safety-log.md # Confirmations for high-impact actions
31└── operation-log.md # Search and route operation IDs with outcomes
32```
33
34## Quick Reference
35
36| Topic | File |
37|-------|------|
38| Setup and first-run behavior | `setup.md` |
39| Memory structure | `memory-template.md` |
40| Command hierarchy and probes | `command-paths.md` |
41| Deterministic operation flows | `operation-patterns.md` |
42| Safety checklist before action | `safety-checklist.md` |
43| Failure handling and recovery | `troubleshooting.md` |
44
45## Data Storage
46
47All skill files are stored in `~/apple-maps/`.
48Before creating or changing local files, describe the planned write and ask for confirmation.
49
50## Core Rules
51
52### 1. Use Apple Maps URL Workflows as Primary Interface
53- Build map requests as explicit Apple Maps URLs and launch with `open -a Maps`.
54- Prefer documented URL parameters instead of UI-only automation.
55
56### 2. Probe Command Path Before Operations
57- Verify command availability in strict order: `open`, `shortcuts`, `osascript`.
58- If only fallback paths are available, explain capability limits before executing.
59
60### 3. Keep Searches Bounded and Deterministic
61- Require clear intent: query text, optional area, and optional map zoom/context.
62- For ambiguous requests like "best restaurants", ask for location context before launching Maps.
63
64### 4. Preview Generated URL Before Execution
65- For every action, show the final URL and explain major parameters.
66- If the query contains user-sensitive text, confirm before opening or sharing.
67
68### 5. Confirm High-Impact Actions
69- Require explicit confirmation for route launches with destination changes, share-link generation, and repeated bulk opens.
70- For repeated actions, present a count and require a second confirmation.
71
72### 6. Verify Result State After Launch
73- After opening Maps, summarize expected visible outcome (query, destination, mode).
74- If result does not match intent, refine parameters instead of retrying blindly.
75
76### 7. Minimize Data Exposure
77- Use minimal query strings needed for the requested task.
78- Do not send map queries to undeclared third-party APIs.
79
80## Common Traps
81
82- Launching vague searches without area context -> noisy, low-value results.
83- Sharing raw links that include private notes -> accidental disclosure.
84- Using UI scripting as default path -> brittle behavior across locales.
85- Opening many candidate links at once -> user loses context quickly.
86- Assuming route mode without confirmation -> wrong transport directions.
87
88## External Endpoints
89
90| Endpoint | Data Sent | Purpose |
91|----------|-----------|---------|
92| https://maps.apple.com | Search text, optional coordinates, routing parameters | Retrieve map, place, and route results in Apple Maps |
93
94No other external endpoint is required by default.
95
96## Security & Privacy
97
98**Data that stays local:**
99- Operational defaults, safety choices, and command reliability notes in `~/apple-maps/`.
100
101**Data that may leave your machine:**
102- Place queries, route origins/destinations, and map parameters sent to Apple Maps when opening URLs.
103
104**This skill does NOT:**
105- Execute undeclared API calls.
106- Persist sensitive location context without user approval.
107- Run bulk opens or share actions without explicit confirmation.
108
109## Trust
110
111By using this skill, map queries and route parameters are sent to Apple Maps.
112Only use this workflow if you trust Apple Maps with that data.
113
114## Related Skills
115Install with `clawhub install <slug>` if user confirms:
116- `macos` - macOS command workflows and automation patterns.
117- `travel` - travel-planning flows and destination strategy.
118- `restaurants` - food venue discovery and shortlist workflows.
119- `car-rental` - route-linked transport planning.
120
121## Feedback
122
123- If useful: `clawhub star apple-maps`
124- Stay updated: `clawhub sync`
modbender