- name
- spotify
- description
- Control Spotify playback, search music, manage playlists, generate discovery playlists, and analyze listening habits via the Spotify Web API. Use when asked to play/pause/skip music, search for songs, manage playlists, get recommendations, check what's playing, or anything Spotify-related. Triggers on "spotify", "play music", "what song", "playlist", "spotify play", "spotify pause", "spotify search".
- env
- description
- Spotify app client ID (or set in config.json)
- required
- false
- description
- Spotify app client secret (or set in config.json)
- required
- false
- description
- OAuth redirect URI (default http://127.0.0.1:3000/callback)
- required
- false
Spotify Skill
Control Spotify playback, manage your library, discover music, and analyze listening habits.
Prerequisites
- Create a Spotify app at developer.spotify.com
- Add a redirect URI (e.g.
http://127.0.0.1:3000/callback) - Copy
config.example.jsontoconfig.jsonand fill in your credentials - Required scopes are auto-requested during auth
cp config.example.json config.json
# Edit config.json with your client_id and client_secretFirst-Time Authorization
python3 scripts/auth.py authOpens a browser for OAuth2. After authorizing, paste the code parameter from the redirect URL:
python3 scripts/auth.py auth <code>Tokens are saved to config.json and auto-refreshed. For headless setups, run auth on a machine with a browser, then copy config.json.
Commands
Run via python3 scripts/spotify.py <command> [args]
Playback
| Command | Args | Description | ||
|---|---|---|---|---|
now-playing | — | Current track, artist, album, progress | ||
play | [uri] | Resume playback, optionally with a specific track URI | ||
pause | — | Pause playback | ||
next | — | Skip to next track | ||
prev | — | Previous track | ||
seek | position_ms | Seek to position in ms | ||
volume | 0-100 | Set volume percentage | ||
shuffle | `on\ | off` | Toggle shuffle | |
repeat | `off\ | track\ | context` | Set repeat mode |
queue-add | uri | Add track to queue | ||
queue | — | Get current queue | ||
devices | — | List available devices | ||
transfer | device_id | Transfer playback to device |
Search & Discover
| Command | Args | Description |
|---|---|---|
search | query | Search tracks, artists, albums, playlists |
recommendations | [track_id] | Get recommendations seeded from a track |
audio-features | track_id | Danceability, energy, tempo, key, etc. |
Library
| Command | Args | Description |
|---|---|---|
saved-tracks | [limit] | Get saved/liked tracks |
save | id1 id2 ... | Save tracks to library |
playlists | [limit] | List your playlists |
playlist-tracks | playlist_id | Get tracks in a playlist |
create-playlist | name [description] | Create a new playlist |
edit-playlist | playlist_id [new_name] | Edit playlist name/description |
add-to-playlist | playlist_id uri1 ... | Add tracks to playlist |
remove-from-playlist | playlist_id uri1 ... | Remove tracks from playlist |
play-playlist | playlist_id | Start playing a playlist from the beginning |
smart-playlist | name [source] [limit] [time_range] | Auto-generate playlist (see below) |
claw-list | [name] [seeds] [per_seed] | Discovery playlist (see below) |
User Data
| Command | Args | Description | ||
|---|---|---|---|---|
me | — | Your Spotify profile | ||
top-tracks | `[short\ | medium\ | long_term]` | Your top tracks |
top-artists | `[short\ | medium\ | long_term]` | Your top artists |
recent | [limit] | Recently played tracks |
Smart Playlists
smart-playlist auto-generates playlists from your listening data:
# From your top tracks (last 6 months)
python3 scripts/spotify.py smart-playlist "My Favorites" top 30 medium_term
# From your liked/saved tracks
python3 scripts/spotify.py smart-playlist "Liked Mix" saved 20
# Recommendations based on your top tracks (discovers new music)
python3 scripts/spotify.py smart-playlist "Discover Weekly DIY" top-recs 30 short_termSources: top (most played), saved (liked songs), top-recs (recommendations from top tracks) Time ranges: short_term (~4 weeks), medium_term (~6 months), long_term (years)
Claw-List (Discovery Playlists)
claw-list creates a discovery playlist with diverse seeds from your top/saved tracks, plus mood-matched related tracks:
# Default: 5 seeds × 5 related tracks = 30 tracks
python3 scripts/spotify.py claw-list "My Mix"
# Custom: 8 seeds, 3 related each = 32 tracks
python3 scripts/spotify.py claw-list "Quick Mix" 8 3
# Larger: 10 seeds, 7 related each = 80 tracks
python3 scripts/spotify.py claw-list "Deep Dive" 10 7How it works:
- Picks diverse seed tracks from your top 50 + saved tracks (deduplicates by artist for variety)
- For each seed: analyzes audio features (energy, valence, danceability, etc.) to determine mood
- Adds 2 same-artist deep cuts + (per_seed - 2) mood-matched discovery tracks via search
- Creates the playlist with all tracks interleaved (seed, related, seed, related...)
Agent Usage Patterns
- "Play [song name]" →
searchthe song, thenplaythe first result's URI - "What's playing?" →
now-playing - "Skip/pause/next" → direct command
- "Make me a playlist of..." →
searchfor tracks,create-playlist,add-to-playlist - "Music like X" →
recommendationsseeded from X's track ID - "My top artists this month" →
top-artists short_term - "Make me a discovery mix" →
claw-listwith desired size
URIs
Spotify uses URIs like spotify:track:4cOdK2wGLETKBW3PvgPWqT. Extract the ID from URLs like https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT — the ID is the part after /track/.
API Migration Notes (February 2026)
Spotify's February 2026 API migration removed several endpoints for dev-mode apps. This skill handles them:
- Playlist tracks: Uses
/playlists/{id}/items(new) instead of/tracks(removed). Response field changed fromtracktoitem. - Create playlist: Uses
/me/playlistsinstead of/users/{id}/playlists(removed). - Recommendations:
/recommendationsand/related-artistsmay return 404/403 in dev mode. Claw-list uses search-based discovery as a fallback. - Batch endpoints:
/tracks,/artists,/albums,/browse/new-releasesare removed in dev mode.
Apps in Extended Quota Mode are unaffected. Request extended quota at the Spotify Developer Dashboard if needed.
Config
config.jsonstores OAuth2 tokens and credentials — do not commit or share- Tokens auto-refresh via
auth.py(called transparently byspotify.py) config.example.jsonis the template for new setups- Env vars
SPOTIFY_CLIENT_ID,SPOTIFY_CLIENT_SECRET,SPOTIFY_REDIRECT_URIoverride config.json if set
Requirements
- Python 3.8+
- A Spotify Premium account (for playback controls)
- No external Python packages needed — uses only stdlib