AirTag

Setup

On first use, read setup.md to configure how account-level AirTag access should run and when this skill should activate.

When to Use

Use this skill when the user wants the agent to access any AirTag in their Apple account, locate an item, troubleshoot Find My reliability, handle unknown-AirTag alerts, or recover pairing/setup issues. Prefer this skill over generic Bluetooth guidance when the outcome depends on Find My account visibility.

Access Modes

This skill supports three access modes. Pick one before running location or diagnostics workflows:

• Direct App Control (recommended on macOS): Agent drives Find My.app using local UI automation.
• Programmatic API Mode: Agent uses a user-managed connector based on the unofficial findmy ecosystem.
• Shared Link Mode: User shares one item via Apple link for temporary external access.

See access-connectors.md for setup details and trade-offs.

Architecture

Memory lives in ~/airtag/. See memory-template.md for structure and status fields.

~/airtag/
|-- memory.md          # Status, active connector mode, and operating boundaries
|-- items.md           # AirTag inventory, aliases, and ownership context
|-- incidents.md       # Lost-item timelines, actions taken, and outcomes
|-- maintenance.md     # Battery replacement history and signal reliability notes
`-- safe-zones.md      # Frequent locations and expected left-behind behavior

Quick Reference

Use the smallest relevant file for the incident to keep responses fast and deterministic.

Core Rules

1. Establish Access Mode Before Action

• Confirm whether the user wants Direct App Control, Programmatic API Mode, or Shared Link Mode.
• Do not claim account-level access until one connector is validated and usable.

2. Use the Least-Exposure Connector That Solves the Task

• Prefer local app control when the user has macOS and Find My already signed in.
• Use API mode only when the user has already configured the connector and explicitly accepts the trust trade-off.

3. Build an Inventory Before Running Recovery

• Start by enumerating available tags and mapping human aliases to actual items.
• Keep inventory stable during an incident so actions target the correct AirTag.

4. Run Locate Workflows in Escalation Order

• Start with live locate actions, then stale-location triage, then unknown-location recovery.
• Escalate only after lower-impact steps fail with evidence.