- name
- AirTag
- slug
- airtag
- version
- 1.0.0
- homepage
- https://clawic.com/skills/airtag
- description
- Give your agent controlled access to all AirTags in your Apple account to locate items, run diagnostics, and recover setup failures.
- changelog
- Initial release focused on account-level AirTag access, connector setup, location workflows, diagnostics, and safety handling.
- metadata
- {"clawdbot":{"emoji":"A","requires":{"bins":[]},"os":["darwin","linux","win32"]}}
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
findmyecosystem. - 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 behaviorQuick Reference
Use the smallest relevant file for the incident to keep responses fast and deterministic.
| Topic | File |
|---|---|
| Setup flow | setup.md |
| Memory template | memory-template.md |
| Connector systems and CLI setup | access-connectors.md |
| Account-level location recovery flow | recovery-playbook.md |
| Connection and pairing diagnostics | connection-diagnostics.md |
| Battery and signal reliability | battery-maintenance.md |
| Unknown AirTag safety workflow | anti-stalking-safety.md |
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.
5. Keep Diagnostics and Pairing Deterministic
- Separate connector problems (auth/session/permissions) from AirTag problems (battery, range, pairing).
- Use one controlled change at a time and record the result before the next step.
6. Treat Unknown AirTag Alerts as Safety-Critical
- Prioritize personal safety and risk reduction before technical detail.
- Use
anti-stalking-safety.mdand avoid speculative attribution.
7. Ask Before Persisting Logs or Sensitive Context
- Ask for explicit confirmation before any connector action, location pull, or local write in
~/airtag/. - Never request Apple ID password sharing or guide key extraction inside this skill.
Common Traps
- Claiming there is an official public AirTag account API -> false expectation and setup failures.
- Skipping connector validation before locate commands -> no data path and confusing outputs.
- Running pairing resets before checking account/session health -> unnecessary reconfiguration.
- Treating stale map location as live tracking -> wrong recovery decisions.
- Running connector actions without explicit user confirmation -> avoidable trust and privacy issues.
- Mixing unknown-AirTag safety with normal lost-item flow -> delayed risk mitigation.
External Endpoints
| Endpoint | Data Sent | Purpose |
|---|---|---|
| https://www.icloud.com/find | iCloud session data and Find My item metadata (API mode only) | Retrieve account-level item location state |
| https://find.apple.com | Shared item location data from user-created link | Temporary access to one lost item for recovery support |
No other data is sent externally.
Security & Privacy
Data that leaves your machine:
- Apple account session traffic to Find My services when a connector is active.
- Optional shared-link data when using Shared Link Mode.
Data that stays local:
- User-approved incident notes and connector context under
~/airtag/.
This skill does NOT:
- Use undeclared endpoints.
- Ask for raw Apple ID passwords by default.
- Store logs outside
~/airtag/for this skill. - Modify its own
SKILL.md.
Trust
Programmatic API Mode depends on third-party tooling for Apple private protocols. Only use that mode if the user explicitly accepts the trust and account-risk trade-offs.
Related Skills
Install with clawhub install <slug> if user confirms:
ios- iOS behavior, permissions, and system troubleshootingbluetooth- Bluetooth discovery and connectivity stability workflowshomepod- Apple ecosystem troubleshooting patterns for shared environmentstravel- Lost-item prevention and movement planning during tripssiri- Voice command reliability for Apple device interactions
Feedback
- If useful:
clawhub star airtag - Stay updated:
clawhub sync