HomePod

Set up, troubleshoot, and optimize HomePod and HomeKit audio workflows with reliable Siri control and room-aware playback tuning.

Security Scan

The skill's instructions, storage, and required actions are coherent with a HomePod/HomeKit troubleshooting and control tool; it requests no external credentials and is instruction-only, with local network control via user-confirmed commands.

Purpose & Capability

Name/description (HomePod/HomeKit setup and troubleshooting) match the skill contents: runbook text, diagnostics, and direct-control guidance. References to atvremote and local network control are appropriate for Apple TV/HomePod control and are called out in the runbook as required preconditions.

Instruction Scope

SKILL.md and auxiliary files limit actions to diagnostics, local network control, and notes stored under ~/homepod/. Mutating actions require explicit target and user confirmation; instructions emphasize read-only checks first and guardrails for destructive changes. No instructions ask the agent to read unrelated system files or exfiltrate data.

Install Mechanism

No install spec or code files — instruction-only skill — so nothing is downloaded or installed by the skill itself. The runbook expects third-party tools (e.g., atvremote) to be present but does not attempt to install them.

Credentials

The skill requests no environment variables, credentials, or config paths. It documents local storage under ~/homepod/ and explicitly forbids storing pairing secrets in memory. Requested access is proportional to the stated purpose.

Persistence & Privilege

The skill persists troubleshooting state and logs in the user's home directory (~/homepod/). This is reasonable for a troubleshooting skill, but it's persistent data on disk — users should be aware and review stored notes. The skill is not always-enabled and does not request elevated system privileges.

Assessment

This skill appears coherent and low-risk: it only contains runbooks and will create/read files under ~/homepod/ and use local-network commands (e.g., atvremote) when you explicitly ask it to run mutating commands. Before installing: 1) ensure you trust the skill source; 2) confirm you are comfortable with a folder ~/homepod/ being created and storing troubleshooting notes; 3) install and verify any required third-party tools (like atvremote) yourself — the skill will not install them; 4) avoid letting the agent run mutating commands without explicit confirmation and never let it store pairing secrets. If you want extra assurance, open the SKILL.md and the runbooks to verify the exact commands it suggests before using direct-control flows.

Setup

On first use, read setup.md for activation preferences and baseline context.

When to Use

Use this skill when tasks involve HomePod setup, direct playback control, Siri playback issues, Home app automations, or multiroom audio stability. Prefer this over generic audio advice when Apple Home ecosystem constraints drive the outcome.

Architecture

Memory lives in ~/homepod/. See memory-template.md for structure.

~/homepod/
|-- memory.md              # Status, activation boundaries, and current setup
|-- homes.md               # Home topology and device mapping
|-- automation-log.md      # Trigger failures, fixes, and validation results
`-- network-notes.md       # Wi-Fi, Thread, and router behavior notes

Quick Reference

Use the smallest relevant file for the current incident to keep troubleshooting focused.

Topic	File
Setup process	setup.md
Memory template	memory-template.md
Direct connection and control	direct-control.md
Network triage flow	network-diagnostics.md
Automation reliability playbook	automation-playbook.md
Siri failure recovery map	siri-recovery.md

Core Rules

1. Confirm Real Topology Before Advice

• Capture HomePod model, software version, home hub role, and active network layout before suggesting fixes.
• Do not assume Thread, stereo pairs, or eARC are available without explicit confirmation.

2. Separate Network, Device, and Service Failures

• Classify each incident as local network path, HomePod device state, or cloud service dependency.
• Apply the narrowest fix first and re-test before moving to broader resets.

3. Keep Automation Debugging Deterministic

• For each failing automation, log trigger, condition, expected action, and actual result in one record.
• Test one change at a time so root cause remains attributable.

4. Validate Multiroom Audio with Repeatable Checks

• Test sync, handoff, and output routing with a fixed sequence across all target rooms.
• Treat intermittent latency as a measurable defect, not user error.

5. Protect User Privacy and Household Boundaries

• Keep notes focused on devices, states, and failures, never on raw voice transcripts or personal content.
• If account-level actions are needed, explain impact and request explicit confirmation first.

6. Prefer Reversible Fixes Before Factory Reset

• Start with service restart, network path validation, and accessory reassociation before destructive actions.
• Reserve full reset workflows for verified dead-end states only.

7. Execute Direct Control in Guarded Mode

• For command execution, require explicit target and intent confirmation before any mutating action.
• Use direct-control.md and run read-only commands first (scan, device_info, playing, volume) before play, pause, stop, or set_volume.

Common Traps

• Treating every Siri error as network related -> repeated failures because account or Home hub state was never checked.
• Resetting devices before collecting evidence -> no reproducible signal and slower recovery.
• Changing multiple automation variables at once -> unclear root cause and unstable behavior.
• Ignoring software version drift across devices -> non-deterministic automation and audio routing outcomes.
• Testing only one room in multiroom setups -> latent sync issues missed until production use.
• Sending control commands to ambiguous device names -> wrong-room playback changes and user trust loss.

Security & Privacy

Data that leaves your machine:

• None by default. Direct control uses local network traffic to HomePod or Apple TV devices.

Data that stays local:

• Setup context and troubleshooting notes in ~/homepod/.

This skill does NOT:

• Send undeclared network requests.
• Execute mutating control commands without target confirmation.
• Modify files outside ~/homepod/ for storage.
• Modify its own SKILL.md.

Related Skills

Install with clawhub install <slug> if user confirms:

• smart-home - Cross-vendor smart-home architecture and reliability patterns
• siri - Siri interaction and intent quality troubleshooting
• wifi - Local network diagnostics for latency and packet-loss issues
• audio - Audio routing, quality, and playback reliability workflows
• ios - iOS-side Home app and device configuration support

Feedback

• If useful: clawhub star homepod
• Stay updated: clawhub sync