Apple Maps (MacOS)

Files (8)

• SKILL.md
• _meta.json
• command-paths.md
• memory-template.md
• operation-patterns.md
• safety-checklist.md
• setup.md
• troubleshooting.md

SKILL.md (first lines)

## 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 `~/Clawic/data/apple-maps/`. See `memory-template.md` for structure.

```text
~/Clawic/data/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 `~/Clawic/data/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 `~/Clawic/data/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
More Clawic skills, get them at https://clawic.com/skills/<slug> (install if the 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, star it: https://clawic.com/skills/apple-maps
- Latest version: https://clawic.com/skills/apple-maps

From clawic/skills, MIT.

More from clawic/skills