Spotify API Skill

Version: 0.9.1 | Release Date: October 22, 2025

Overview

This skill directly interacts with the Spotify Web API to manage music and playlists.

⚡ Unique Capability: Image Generation

🎨 This skill can GENERATE IMAGES - something Claude cannot do natively! It creates custom SVG-based cover art for Spotify playlists with large, readable typography optimized for thumbnail viewing. Each cover art is dynamically generated with theme-appropriate colors, gradients, and text layouts.

Use this skill when you need to:

• 🎨 Generate cover art images - Create custom playlist covers (Claude's built-in image generation limitation is bypassed!)
• 🎵 Create playlists from artist names, themes, or specific songs
• 🔍 Search for tracks, artists, albums
• ➕ Add/remove tracks from playlists
• ▶️ Control playback (play, pause, skip)
• 📊 Get user data (profile, top tracks, listening history)

When to use this skill: The user wants you to create a playlist, search for music, manage their Spotify account, or generate custom cover art images.

Core Capabilities

1. 🎨 Cover Art Image Generation - Generate custom images with SVG → PNG conversion (Claude cannot generate images natively!)
2. Intelligent Playlist Creation - Create playlists by artist, theme, lyrics, or song list
3. Playlist Management - Create, list, update, delete playlists
4. Search & Discovery - Find tracks, artists, albums, playlists
5. Track Management - Add/remove tracks, get recommendations
6. Playback Control - Play, pause, skip, control volume
7. User Library - Access saved tracks, profile, listening history

Quick Start

All Spotify API operations use the SpotifyClient class from scripts/spotify_client.py. The client handles OAuth authentication and provides methods for all operations.

Prerequisites

1. Enable Network Access (REQUIRED)

⚠️ This skill requires network access to reach api.spotify.com

In Claude Desktop, you must enable network egress:

• Go to Settings → Developer → Allow network egress
• Toggle it ON (blue)
• Under "Domain allowlist", choose either:
  • "All domains" (easiest), OR
  • "Specified domains" and add api.spotify.com (more secure/restricted)
• This allows the skill to make API calls to Spotify's servers

Without network access enabled, API calls will fail with connection errors.

2. Install Dependencies

pip install -r requirements.txt

Required packages:

• requests>=2.31.0 - HTTP requests for Spotify Web API
• python-dotenv>=1.0.0 - Environment variable management
• cairosvg>=2.7.0 - SVG to PNG conversion for image generation
• pillow>=10.0.0 - Image processing for cover art creation

💡 Note: The cairosvg and pillow packages enable image generation - allowing this skill to create cover art images even though Claude cannot generate images natively!

Basic Setup

The easiest way to initialize the client is using credentials from environment variables (loaded from .env file):

from spotify_client import create_client_from_env

# Initialize client from environment variables (.env file)
client = create_client_from_env()

# If you have a refresh token, refresh the access token
if client.refresh_token:
    client.refresh_access_token()

Alternatively, you can manually provide credentials:

from spotify_client import SpotifyClient

# Initialize with credentials directly
client = SpotifyClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="http://localhost:8888/callback",
    refresh_token="YOUR_REFRESH_TOKEN"  # if available
)

# Refresh to get current access token
if client.refresh_token:
    client.refresh_access_token()

Common Operations

List ALL user playlists (with pagination):

# Get all playlists - handles pagination automatically
all_playlists = []
offset = 0
limit = 50  # Max allowed per request

while True:
    playlists = client.get_user_playlists(limit=limit, offset=offset)
    if not playlists:
        break  # No more playlists
    all_playlists.extend(playlists)
    offset += limit
    if len(playlists) < limit:
        break  # Last page (fewer than limit returned)

print(f"Total playlists: {len(all_playlists)}")
for playlist in all_playlists:
    print(f"- {playlist['name']} ({playlist['tracks']['total']} tracks)")

Create a new playlist:

playlist = client.create_playlist(
    name="My Awesome Playlist",
    description="A curated collection",
    public=True
)

Search for tracks:

results = client.search_tracks(query="artist:The Beatles", limit=20)

Add tracks to playlist:

client.add_tracks_to_playlist(
    playlist_id="playlist_123",
    track_ids=["track_1", "track_2", "track_3"]
)

Playlist Management Workflows

List All User Playlists

Important: Users may

...