spotify

name: spotify description: "Spotify: play, search, queue, manage playlists and devices." version: 1.0.0 author: Hermes Agent license: MIT prerequisites: tools: [spotify_playback, spotify_devices, spotify_queue, spotify_search, spotify_playlists, spotify_albums, spotify_library] metadata: hermes: tags: [spotify, music, playback, playlists, media] related_skills: [gif-search]

Control the user's Spotify account via the Hermes Spotify toolset (7 tools). Setup guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify

When to use this skill

User says "play X", "pause", "skip", "queue up X", "what's playing", "search for X", "add to my X playlist", "make a playlist", "save this to my library", etc.
User says "set up Spotify", "configure Spotify", "connect Spotify", "auth Spotify", "authenticate Spotify"
Tools are missing (403/404 errors indicate not configured)
401 Unauthorized on any Spotify tool call (token expired — re-auth needed)

Setup & Authentication

Spotify requires a one-time OAuth setup using PKCE. You need a free Spotify Developer App — the CLI walks you through creating one.

One-shot — interactive (if TUI available)

hermes tools

Scroll to the "🎵 Spotify" section, press Space to toggle it on, then s to save. Hermes drops you into the OAuth flow immediately — if you don't have a Spotify Developer App yet, it walks you through creating one.

One-shot — non-interactive (preferred from agent terminal)

hermes tools enable spotify

No scrolling, no key-presses. Works from any terminal tool. Verify with:

hermes tools list | grep spotify
# → should show: ✓ enabled  spotify  🎵 Spotify

After enabling, config.yaml will list spotify under platform_toolsets.cli and known_plugin_toolsets.cli.

Two-step (manual)

Create a Spotify Developer App at https://developer.spotify.com/dashboard:
- App name: anything (e.g. hermes-agent)
- Description: anything
- Redirect URI: http://127.0.0.1:43827/spotify/callback
- API/SDK: Web API
Open the app's Settings and copy the Client ID
Run:
```
hermes auth spotify
```
Paste the Client ID when prompted — this opens a browser tab for authorization
Authorize — tokens are stored in ~/.hermes/auth.json and auto-refresh

Important: PTY/terminal limitation

hermes auth spotify is interactive — it asks for the Client ID and opens a browser. You CANNOT run this through Hermes' terminal tool (it needs real user input). Tell the user to run it themselves in their own terminal.

Re-authentication

If tokens expire or you get 401 Unauthorized:

hermes auth spotify

The stored app credentials are reused — no need to visit the developer dashboard again.

The 7 tools

spotify_playback — play, pause, next, previous, seek, set_repeat, set_shuffle, set_volume, get_state, get_currently_playing, recently_played
spotify_devices — list, transfer
spotify_queue — get, add
spotify_search — search the catalog
spotify_playlists — list, get, create, add_items, remove_items, update_details
spotify_albums — get, tracks
spotify_library — list/save/remove with kind: "tracks"|"albums"

Playback-mutating actions require Spotify Premium; search/library/playlist ops work on Free.

Canonical patterns (minimize tool calls)

"Play <artist/track/album>"

One search, then play by URI. Do NOT loop through search results describing them unless the user asked for options.

spotify_search({"query": "miles davis kind of blue", "types": ["album"], "limit": 1})
→ got album URI spotify:album:1weenld61qoidwYuZ1GESA
spotify_playback({"action": "play", "context_uri": "spotify:album:1weenld61qoidwYuZ1GESA"})

For "play some " (no specific song), prefer types: ["artist"] and play the artist context URI — Spotify handles smart shuffle. If the user says "the song" or "that track", search types: ["track"] and pass uris: [track_uri] to play.

"What's playing?" / "What am I listening to?"

Single call — don't chain get_state after get_currently_playing.

spotify_playback({"action": "get_currently_playing"})

If it returns 204/empty (is_playing: false), tell the user nothing is playing. Don't retry.

"Pause" / "Skip" / "Volume 50"

Direct action, no preflight inspection needed.

spotify_playback({"action": "pause"})
spotify_playback({"action": "next"})
spotify_playback({"action": "set_volume", "volume_percent": 50})

"Add to my playlist"

spotify_playlists list to find the playlist ID by name
Get the track URI (from currently playing, or search)
spotify_playlists add_items with the playlist_id and URIs

spotify_playlists({"action": "list"})
→ found "Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo
spotify_playback({"action": "get_currently_playing"})
→ current track uri = spotify:track:0DiWol3AO6WpXZgp0goxAV
spotify_playlists({"action": "add_items",
                   "playlist_id": "37i9dQZF1DX4wta20PHgwo",
                   "uris": ["spotify:track:0DiWol3AO6WpXZgp0goxAV"]})

"Create a playlist called X and add the last 3 songs I played"

spotify_playback({"action": "recently_played", "limit": 3})
spotify_playlists({"action": "create", "name": "Focus 2026"})
→ got playlist_id back in response
spotify_playlists({"action": "add_items", "playlist_id": <id>, "uris": [<3 uris>]})

"Save / unsave / is this saved?"

Use spotify_library with the right kind.

spotify_library({"kind": "tracks", "action": "save", "uris": ["spotify:track:..."]})
spotify_library({"kind": "albums", "action": "list", "limit": 50})

"Transfer playback to my "

spotify_devices({"action": "list"})
→ pick the device_id by matching name/type
spotify_devices({"action": "transfer", "device_id": "<id>", "play": true})

Critical failure modes

403 Forbidden — No active device found on any playback action means Spotify isn't running anywhere. Tell the user: "Open Spotify on your phone/desktop/web player first, start any track for a second, then retry." Don't retry the tool call blindly — it will fail the same way. You can call spotify_devices list to confirm; an empty list means no active device.

403 Forbidden — Premium required means the user is on Free and tried to mutate playback. Don't retry; tell them this action needs Premium. Reads still work (search, playlists, library, get_state).

204 No Content on get_currently_playing is NOT an error — it means nothing is playing. The tool returns is_playing: false. Just report that to the user.

429 Too Many Requests = rate limit. Wait and retry once. If it keeps happening, you're looping — stop.

401 Unauthorized after a retry — refresh token revoked. Tell the user to run hermes auth spotify again.

403 Forbidden on ALL write operations (POST/PUT/DELETE) despite having write scopes — check the /v1/me response. If product: None and country: None, the token is read-only at the account level. This is NOT a scope issue — the granted scopes may include playlist-modify-public/private, user-library-modify, etc., but Spotify still rejects writes. Common causes:

Account not fully verified / pending setup
Account region restricted for API write operations
OAuth token issued with write scopes but the underlying account is a restricted tier

Diagnosis:

import json, urllib.request
TOKEN = open_token()  # from auth.json providers.spotify.access_token
req = urllib.request.Request("https://api.spotify.com/v1/me",
    headers={"Authorization": f"Bearer {TOKEN}"})
with urllib.request.urlopen(req) as resp:
    me = json.loads(resp.read())
# product will be "free", "premium", or None (restricted)
print(me.get("product"), me.get("country"))

If confirmed read-only: You can still read everything (playlists, saved tracks, search), but you CANNOT create playlists, add tracks, save to library, or modify anything. Tell the user their Spotify account has write restrictions and suggest they open the playlist URL in the Spotify app to add tracks manually.

Workaround for creating a playlist: If /v1/users/{user_id}/playlists returns 403, try /v1/me/playlists instead — it uses the authenticated user implicitly and may bypass the endpoint-specific block.

# Instead of:
POST https://api.spotify.com/v1/users/{user_id}/playlists  # may 403
# Use:
POST https://api.spotify.com/v1/me/playlists  # may work

Tool 'spotify_*' does not exist — the Spotify toolset isn't enabled in this session. Run hermes tools enable spotify (non-interactive) or hermes tools (interactive toggle), then the tools only become available in the next session. Tell the user to /reset (new session — context is lost) or start a fresh conversation. The tools themselves gate on providers.spotify in ~/.hermes/auth.json — enabling alone is not enough; OAuth must succeed first. If the tools still don't exist after enabling + session restart, run hermes auth spotify interactively (see Setup).

URI and ID formats

Reference files:

references/auth-diagnostics.md — full auth troubleshooting table, auth.json structure

references/playlist-pagination-and-token-debug.md — pagination structure for 1800+ track playlists, random selection pattern, read-only token diagnosis

Spotify uses three interchangeable ID formats. The tools accept all three and normalize:

URI: spotify:track:0DiWol3AO6WpXZgp0goxAV (preferred)
URL: https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV
Bare ID: 0DiWol3AO6WpXZgp0goxAV

When in doubt, use full URIs. Search results return URIs in the uri field — pass those directly.

Entity types: track, album, artist, playlist, show, episode. Use the right type for the action — spotify_playback.play with a context_uri expects album/playlist/artist; uris expects an array of track URIs.

What NOT to do

Don't call get_state before every action. Spotify accepts play/pause/skip without preflight. Only inspect state when the user asked "what's playing" or you need to reason about device/track.
Don't describe search results unless asked. If the user said "play X", search, grab the top URI, play it. They'll hear it's wrong if it's wrong.
Don't retry on 403 Premium required or 403 No active device. Those are permanent until user action.
Don't retry on 403 Forbidden for write operations (create playlist, add tracks, save library). Check /v1/me for product: None first — if confirmed, the token is read-only and retrying won't help. Tell the user and suggest manual action in the Spotify app.
Don't use spotify_search to find a playlist by name — that searches the public Spotify catalog. User playlists come from spotify_playlists list.
Don't mix kind: "tracks" with album URIs in spotify_library (or vice versa). The tool normalizes IDs but the API endpoint differs.