How to use the Spotify agent skill: install, trigger and control

What the Spotify skill makes the agent do

Once installed, the agent can search Spotify, follow or create playlists, add tracks, read what is playing, manage your library, and control playback on an active device. All of this runs through Tools/Spotify.ts, a deterministic command-line tool, so each request becomes one tool call keyed by IDs or URIs.

The skill does not recommend music and does not generate songs. The directory description lists those as separate skills, and it also excludes editing audio.

• Search for tracks, playlists and other items
• Follow playlists and create new ones
• Add tracks to playlists and read your playlists and library
• Read the currently playing track
• Control playback such as skip or volume (Premium and an active device required)

Install the Spotify skill: download, unzip and place it

Download the ZIP from this page and unzip it. Place the Spotify folder in your personal skills directory at ~/.claude/skills/, or in a project's .claude/skills/ folder if you want it limited to one project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/Spotify/
• Project install: .claude/skills/Spotify/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Set up the three Spotify credentials

The skill needs a free Spotify developer app for a client ID and client secret, plus a refresh token from a one-time authorization step. All three are stored as keys in ~/.claude/.env: SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET and SPOTIFY_REFRESH_TOKEN. The skill keeps no other config file.

Setup.md walks through creating the developer app and the three keys. Run the authorization with the auth command, which the Authorize intent covers. The redirect URI in your app dashboard must be exactly http://127.0.0.1:8888/callback, using 127.0.0.1 rather than localhost.

• Create a Spotify developer app and note its client ID and secret
• Add the three SPOTIFY_ keys to ~/.claude/.env
• Set the dashboard Redirect URI to http://127.0.0.1:8888/callback
• Run the auth command once to obtain the refresh token

Confirm the setup works

The proof command lists a single playlist. If it returns playlist rows, the credentials and token are working and you can start issuing requests. If the tool exits with code 1 and points at Setup.md, one of the credentials is missing.

• A successful run returns real playlist rows with no session restart and no MCP registration needed
• Exit code 1 means credentials are missing; check Setup.md

Trigger the skill with natural requests

You do not need to name the tool. The skill is triggered by phrases such as spotify, play on spotify, add to my spotify, follow this playlist, save playlist, create a spotify playlist, add tracks, what's playing, my playlists, queue this, skip track, set volume, spotify search, control spotify, or my spotify library.

Phrase requests as you would say them out loud. The agent resolves names to IDs or URIs first, so if a track or playlist matches ambiguously it reports the candidates and adds nothing for that item.

• "Add this playlist link to my Spotify" (a playlist you do not own is followed, not copied)
• "Make me a focus-music playlist and fill it" (creates a playlist and adds the matched tracks)
• "What's playing?"
• "Skip this" or "turn it down" (playback, needs Premium and an active device)

Safety: scripts, network and account write access

This skill runs scripts and uses the network. It calls the Spotify Web API directly, and it can change your playlists, library and playback. Only install it if you are comfortable giving an agent write access to your music account.

Tokens refresh automatically on each run, and the tool saves rotated refresh tokens itself. Credentials live only in ~/.claude/.env, so keep that file private. The skill does not read files under LIFEOS/USER/.

• Runs scripts and makes network calls to Spotify
• Can modify playlists, library and playback
• Credentials stored only as environment keys, never in the skill folder
• Search works without user login, but other commands need the refresh token

Troubleshooting common errors

A 401 error on every call usually means the refresh token has died, for example after a password change or revoked access. Re-run the auth command to get a new one. Playback commands that fail often mean there is no active device or the account is not Premium.

• 401 on every call: re-run the auth command
• Redirect mismatch: make the dashboard URI exactly http://127.0.0.1:8888/callback
• Playback failing: confirm Premium and an open Spotify app on a device
• Playlist rows missing a track count: this is expected; the tool omits the count when Spotify does not return it