Spotify

Purpose

Work with the Spotify Web API: read the current user's profile, playlists, playlist tracks, and top tracks/artists; search the Spotify catalog; and (each behind an exact-match confirmation) create playlists, add tracks to playlists, and save tracks to the user's library. Reach for this when the user wants to look at or curate their Spotify content from chat.

Tooling

All commands go through bin/spotify.py:

bin/spotify.py auth                                # verify the OAuth token
bin/spotify.py me                                  # current user's profile
bin/spotify.py playlists --limit 50                # list the user's playlists
bin/spotify.py playlist-tracks --playlist-id PID   # tracks in a playlist
bin/spotify.py top-tracks --limit 10               # user's top tracks
bin/spotify.py top-artists --limit 10              # user's top artists
bin/spotify.py search --query "khruangbin"          # search the catalog
bin/spotify.py playlist-create --name "Focus" \
    --confirm 'create playlist "Focus"'            # new playlist (private unless --public)
bin/spotify.py playlist-add --playlist-id PID \
    --uris "spotify:track:AAA,spotify:track:BBB" \
    --confirm "add 2 track(s) to playlist PID"     # append tracks
bin/spotify.py save-track --ids "AAA,BBB" \
    --confirm "save track(s) AAA,BBB to your library"  # save to Liked Songs

--time-range on the top commands takes short_term, medium_term (default), or long_term.

Auth

• Provider id: spotify (credential is collected as custom.spotify)
• Collection: OAuth 2.0 Authorization Code flow via the secure credential flow (credentials.request_api_access); the runtime performs the token exchange/refresh and hands the CLI a fresh Bearer token
• Required scopes: user-read-private, user-read-email, playlist-read-private, playlist-modify-private, playlist-modify-public, user-top-read, user-library-read, user-library-modify. Honesty flag: this scope list is taken from Spotify's public Web API docs and has not been verified in a live flow; if a command returns 403, re-check the scopes granted at approval.
• Allowed hosts: api.spotify.com
• Status check: bin/spotify.py auth

Operating Rules

1. All writes need confirmation on every call. playlist-create, playlist-add, and save-track refuse unless --confirm matches the exact string the CLI echoes (it names the playlist, track IDs, or library target). This is stricter than the standing first-use-only rule, chosen because these writes touch the user's personal library and are visible to other people when public.
2. playlist-create defaults to a private playlist; add --public only when the user explicitly asks for a public one.
3. Search and top-lists are read-only and need no confirmation.
4. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/spotify.py). Do not print, log, or transmit the token.

Files

• SKILL.md
• bin/spotify.py

Maturity

Draft: written from Spotify's public Web API docs; not yet live-tested end-to-end.