How to use the Sonos Playback Control agent skill

What is an agent skill and what does the sonos skill do?

An agent skill is a folder containing a SKILL.md file of instructions that an AI agent reads when a task matches the skill's description. The skill does not add new hardware support by itself. It tells the agent how to work with the Sonos tooling already available in your project.

The skill covers music search and playback by track, album, artist, playlist or station, adding or replacing the queue, pause, resume, skip, seek, shuffle and repeat, setting volume or mute for a room or group, moving playback between rooms, and playing YouTube audio through Sonos when local tooling supports it.

• Search and play music by track, album, artist, playlist, or station
• Add or replace the queue
• Pause, resume, skip, seek, shuffle, repeat
• Set volume or mute for a room or group
• Move or group playback between rooms
• Play YouTube audio through Sonos when supported by local tooling

What you need before installing the sonos skill

The skill depends on existing local Sonos tooling or a CLI in the current repository. The skill files do not include a Sonos API client, so without such tooling the agent has nothing to run and the skill will not work out of the box.

The 1Password CLI, op, is optional. The skill only uses it when the repository's rules call for it for secrets or account authentication.

• Sonos speakers on your network
• An existing Sonos control script or CLI in the repository you work in
• Optional: the 1Password CLI (op), only if your repo's rules require it

Install the sonos skill from a ZIP download

Download the ZIP for the sonos skill from this page and unzip it. The package contains agents/openai.yaml and SKILL.md.

For a personal install, unzip the folder into ~/.claude/skills/. To scope the skill to one project, unzip it into the project's .claude/skills/ folder instead.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: place the skill folder in ~/.claude/skills/
• Project only: place the skill folder in your project's .claude/skills/
• Claude apps: upload under Settings → Capabilities → Skills

How do you trigger the sonos skill with natural requests?

You do not need a special command. Ask for what you want in plain language, mentioning Sonos, the room and the music. The agent matches your request to the skill's description and follows its workflow.

If your request is ambiguous, the skill tells the agent to confirm the target room or group before acting, so be specific when you have several speakers.

• "Play the Miles Davis playlist in the kitchen."
• "Set the living room volume to 20."
• "Group the office with the bedroom speaker."
• "Skip to the next track on the patio Sonos."
• "Add this album to the end of the queue in the study."

How the agent works through a request

The skill sets a fixed workflow. The agent first looks for existing repo commands, for example by listing files with rg --files and checking package scripts or CLI help. It then identifies the room or group, the service or source, and the query, URL, playlist, album, artist or track.

Before acting it may read the current state of rooms, groups, now playing and the queue. It then runs the requested action and checks the state again to verify the result.

• Discover existing repo commands before writing new ones
• Identify the target room, group and source
• Read current state when useful
• Execute the action
• Verify by reading state again

Safety notes: scripts, network and secrets

The skill runs scripts and uses the network, because controlling speakers means sending requests to local tooling and services. Review the scripts in your repository before you let an agent run them.

The skill is built to limit side effects. It tells the agent not to change speaker groups, queues or playback unless you ask, and to keep network debugging out of scope unless you explicitly request diagnostics. For secrets and account auth it checks environment variables and profiles first.

• Speaker groups, queues and playback are left alone unless you ask for a change
• Network and debug work is out of scope unless you request diagnostics
• Secrets are checked in environment or profile first; op is used only through repo or AGENTS rules
• YouTube URLs are treated as media sources, not download requests

Tips and YouTube limits

Keep your Sonos control scripts documented in the repo so the agent can find them with its first discovery step. If you ask for something the local tooling cannot do, the skill tells the agent to state the constraint rather than invent a workaround.

For YouTube, the skill prefers a playable audio URL or a local extraction workflow already present in the repo. It avoids downloading unless you request it, because downloading may breach service terms or copyright.

• Keep Sonos scripts and their usage notes in the repo so they are discoverable
• Name rooms clearly to avoid confirmation questions
• Expect the agent to report when Sonos or the service blocks direct YouTube playback