Skill: ivangdavila/airtag (version 1.0.0)

--- 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 `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. ```text ~/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. | 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.md` and 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 troubleshooting - `bluetooth` - Bluetooth discovery and connectivity stability workflows - `homepod` - Apple ecosystem troubleshooting patterns for shared environments - `travel` - Lost-item prevention and movement planning during trips - `siri` - Voice command reliability for Apple device interactions ## Feedback - If useful: `clawhub star airtag` - Stay updated: `clawhub sync`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)