iCloud

## Setup On first use, read `setup.md` for secure integration guidelines. ## When to Use Use this skill when the user wants agents to interact with their own iCloud account: list devices, retrieve Find My status, inspect iCloud Drive, or pull photo metadata/files. Use it for operational automation with strict safety gates, not for bypassing Apple account security. ## Architecture Memory lives in `~/icloud/`. See `memory-template.md` for structure and status fields. ```text ~/icloud/ |-- memory.md # Status, integration mode, and current account scope |-- operations-log.md # Executed commands, result checks, and rollback notes |-- device-map.md # Known device aliases and stable IDs |-- drive-map.md # iCloud Drive folder map and verified paths `-- safety-events.md # Confirmed risky actions and explicit approvals ``` ## Quick Reference Load only the file needed for the current task. | Topic | File | |-------|------| | Setup flow | `setup.md` | | Memory template | `memory-template.md` | | Authentication and session handling | `auth-session.md` | | Find My operations | `findmy-ops.md` | | iCloud Drive operations | `drive-ops.md` | | Photos operations | `photos-ops.md` | | Safety boundaries and confirmations | `safety-boundaries.md` | ## Core Rules ### 1. Authenticate Locally, Never Through Chat - Never ask the user to paste Apple password, 2FA code, session token, or app password in conversation. - Use interactive local auth with terminal prompts or secure local input prompts only. ### 2. Start Read-Only, Then Escalate - Run read-only discovery first: account reachability, device list, folder listing, metadata checks. - Do not run write operations until read checks pass and scope is explicit. ### 3. Require Explicit Confirmation for Risky Actions - Treat lost mode, message push, file rename/delete, and bulk upload as risky. - Before running risky actions, summarize target, effect, and rollback option, then request explicit confirmation. ### 4. Use Deterministic Verification After Every Action - After each operation, verify expected state with a second read call. - Never report success from command exit code alone. ### 5. Keep Operations Narrow and Idempotent - Operate on one device ID or one file path per step when possible. - Prefer repeat-safe commands and avoid broad wildcard operations. ### 6. Handle 2FA and Session Expiry as Normal State - If Apple invalidates the session, pause destructive operations and re-auth first. - Continue only after session trust is restored and read checks succeed again. ### 7. Persist Only Minimal Operational Context - Store only what improves reliability (IDs, verified paths, successful patterns). - Never persist secrets or raw credential material in local memory files. ## Common Traps - Asking for Apple credentials in chat -> immediate privacy and trust failure. - Running write operations before discovery -> wrong device/path targeted. - Using device names without IDs -> ambiguous actions on similarly named devices. - Assuming session validity across days -> sudden auth failures mid-workflow. - Executing bulk file changes without snapshot -> difficult rollback after mistakes. - Claiming action success without re-read verification -> silent failures reach users. ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | https://idmsa.apple.com | Apple account auth payload during login | Apple ID authentication | | https://setup.icloud.com | Session and webservice negotiation | iCloud service bootstrap | | https://www.icloud.com | Service API requests (Drive/Photos/Find My) | iCloud operations | | https://idmsa.apple.com.cn | Apple account auth payload (China mainland accounts) | Regional Apple ID authentication | | https://setup.icloud.com.cn | Session and webservice negotiation (China mainland accounts) | Regional iCloud bootstrap | | https://pypi.org | Package metadata (install time only) | Install `pyicloud` | | https://files.pythonhosted.org | Package download (install time only) | Install `pyicloud` | No other data is sent externally by this skill's documented workflow. ## Security & Privacy Data that leaves your machine: - Apple account authentication and iCloud API requests needed for requested operations. - Package install traffic only when installing dependencies. Data that stays local: - Optional operational notes under `~/icloud/`. - Local keyring entries managed by the `pyicloud` tool if the user chooses to store password. This skill does NOT: - Bypass Apple security flows or 2FA requirements. - Request undeclared credentials in chat. - Execute undeclared network endpoints. - Modify its own SKILL file. ## Trust By using this skill, you trust Apple iCloud endpoints and the `pyicloud` package. Only install and run this workflow if you trust these services with your account operations. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `cloud-storage` - Cross-provider storage workflows and transfer safety checks - `ios` - Apple device settings, permissions, and account behavior troubleshooting - `macos` - macOS security, keychain, and runtime diagnostics for Apple tooling - `photos` - Media management strategies when iCloud Photos is the main workload ## Feedback - If useful: `clawhub star icloud` - Stay updated: `clawhub sync`