Apple Maps (MacOS)

Search places, open routes, and run Apple Maps workflows on macOS using local CLI commands and shortcut automation with explicit safety checks.

Security Scan

The skill's requested files, command paths, and behaviors align with a macOS Apple Maps automation helper and its local-only data storage and confirmation gates are proportionate to its purpose.

Purpose & Capability

Name/description (Apple Maps automation on macOS) match the declared requirements: macOS-only, command-line paths (open, shortcuts, osascript), and a local config directory. Required binaries and the config path are appropriate for the stated functionality.

Instruction Scope

SKILL.md and supporting docs limit actions to building and launching Apple Maps URLs, probing local command availability, maintaining local logs, and requiring confirmations before sharing or bulk actions. No instructions direct collection of unrelated system data or calls to undeclared third parties.

Install Mechanism

No install spec and no code files (instruction-only) — lowest-risk model. The skill relies on existing macOS tools rather than downloading or installing external code.

Credentials

No environment variables or external credentials requested. The only external endpoint explicitly used is https://maps.apple.com, which is appropriate for Apple Maps URL workflows. Local file writes are restricted to ~/apple-maps/ and the SKILL requires explicit confirmation before creating/updating files.

Persistence & Privilege

The skill stores operational memory and safety logs in a single user-scoped directory (~/apple-maps/) and mandates user confirmation before writes. always:false and normal autonomous invocation are set; confirmations for high-impact actions are enforced in the docs.

Scan Findings in Context

[no_code_files] expected: The regex scanner had nothing to analyze because this is an instruction-only skill; this is expected for a documentation-driven automation skill.

Assessment

This skill appears to do what it claims: build and open Apple Maps URLs from macOS and keep small local logs. Before installing, confirm you are comfortable with files being created under ~/apple-maps/ and with queries being sent to Apple Maps (maps.apple.com). Ensure you understand and approve any use of the Shortcuts or AppleScript fallback paths (they may prompt for permissions). On first run, verify the skill lists the command path it will use and inspect any files it proposes to write; keep sharing disabled unless you explicitly approve each link. If you want tighter control, run initial operations manually and check the generated URLs before allowing the agent to open them automatically.

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