playlist-curator
A skill that lets AI agents reason about music, not just search for tracks. Curate playlists from natural language using audio DNA profiling
Open source Open in the app JSON README (API)
About
A skill that lets AI agents reason about music, not just search for tracks. Curate playlists from natural language using audio DNA profiling, scored recommendations, taste memory, and aesthetic blending across artists, genres, and moods.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- rachel-howell
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 5
- Forks
- 2
- Last push
- 2026-04-09T21:20:59Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
rachel-howell/spotify-playlist-curator/playlist-curator
README
# Spotify Playlist Curator
## Install
**Claude (Marketplace):**
```bash
claude plugin marketplace add rachel-howell/spotify-playlist-curator
claude plugin install playlist-curator
```
**OpenClaw:**
```bash
clawhub install spotify-playlist-curator
```
---
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill that gives AI agents musical intuition. I built this because I was unsatisfied with Spotify’s existing music recommendation features. It allows AI agents to reason deeply about music, getting recommendations based on user requests and then critically considering which ones to include in the playlist it’s making. It gives them a framework that includes audio DNA profiling, multi-source recommendations with scored explanations, and tools for blending aesthetics across artists and genres. And since there’s so much room for thinking and personalization, it provides lots of surface area for fun emergent behavior!
## What can it do?
Describe what you want in natural language. The agent translates your intent into audio features, artist networks, and genre affinities, then builds a playlist grounded in real data.
**Some examples:**
- *"Make me a playlist that combines the sound of Lana Del Rey's 'Venice Bitch' with Mitski's 'My Love Mine All Mine', about an hour long, and don't include 'Mariner's Apartment Complex'"* — seeds from specific tracks, blends both artists' sonic profiles, trims to duration, excludes the named track
- *"Based on the songs I've been listening to lately, pick the high-energy ones and put a playlist together for my gym session. Throw in a few new ones that match the vibe"* — pulls recent listening history, filters by energy and danceability, seeds recommendations from the top matches
- *"Take my road trip playlist and make it more upbeat without losing the indie feel"* — analyzes the existing playlist's audio DNA, recommends tracks that boost energy and danceability while preserving genre affinity
- *"A playlist of only Bjork and Radiohead deep cuts"* — pulls artist catalogs directly, filters by popularity
- *"Find my 'March 2026' playlist, remove all the Drake songs, and add some more relaxed tracks that pair well with what's left"* — locates the playlist by name, removes specific artist's tracks, analyzes the remaining audio profile, recommends new tracks that match
The agent explains its reasoning at every step: which seeds it chose and why, what audio features it's targeting, and what trade-offs it made.
## How it works
The skill is built around three ideas:
### 1. Musical vocabulary
Audio features (energy, danceability, valence, acousticness, tempo, loudness) aren't just numbers — they map to musical concepts the agent uses to reason about requests. "Melancholic" means low valence + moderate energy. "Intimate" means low loudness + high acousticness. The agent speaks this language when making and explaining decisions.
### 2. Multi-source recommendation engine
A 3-tier fallback chain ensures recommendations work even as Spotify deprecates endpoints:
- **Tier 1** — [ReccoBeats](https://reccobeats.com) for similarity-based recommendations and audio feature data
- **Tier 2** — Audio-feature scoring when ReccoBeats recommendations are unavailable but feature data still is
- **Tier 3** — Spotify-only fallback using search, genre overlap, and artist proximity
Each tier produces scored results with human-readable explanations (`"genre match"`, `"audio match: energy=0.05, valence=0.03"`, `"boosted artist"`), so the agent can evaluate and adjust before committing.
### 3. DNA blending
For fusion requests ("X meets Y", "blend these two playlists"), `blend-dna` profiles two track groups independently, computes a target zone in audio-feature space, then scores candidates by how well they sit in the overlap. The output includes per-feature distances so the agent can see exactly where a track falls relative to both source aesthetics.
## Features
| Capability | Details |
|---|---|
| Natural language playlists | Describe a vibe, mood, or reference point — the agent handles seed selection, genre targeting, and audio feature alignment |
| Seed from anything | Specific tracks, artists, existing playlists, genres, or your listening history |
| Audio DNA profiling | Analyze any playlist or set of tracks for energy, danceability, valence, acousticness, tempo, loudness, and more |
| Aesthetic blending | Fuse two distinct musical identities with adjustable weighting |
| Scored recommendations | Every recommendation comes with a composite score and reasons — the agent curates, not just retrieves |
| Constraint mapping | "no X", "more Y", "deep cuts", "bangers", "about an hour" — natural language constraints map to CLI flags |
| Taste memory | Excluded artists, favorite genres, and free-text notes persist across sessions |
| Listening history | Pull from recent plays, top tracks, and top artists across time ranges |
| Playlist operations | Create, modify, analyze, queue tracks, search catalog |
## Setup
### Prerequisites
- Python 3.9+
- A [Spotify Developer](https://developer.spotify.com/dashboard) app (free)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
### 1. Clone and install dependencies
```bash
git clone https://github.com/rachel-howell/spotify-playlist-curator.git
cd spotify-playlist-curator
bash scripts/setup.sh
```
### 2. Configure Spotify credentials
Create an app at [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard). Set the redirect URI to `http://127.0.0.1:8888/callback`.
Add your credentials to `.env`:
```
SPOTIPY_CLIENT_ID=your_client_id_here
SPOTIPY_CLIENT_SECRET=your_client_secret_here
```
### 3. Authenticate
```bash
.venv/bin/python scripts/spotify_auth.py
```
This opens a browser for Spotify OAuth consent and saves your tokens locally.
### 4. Register as a Claude Code skill
Add the skill to your Claude Code configuration so the agent loads it automatically for music-related requests. See the [Claude Code skills documentation](https://docs.anthropic.com/en/docs/claude-code/skills) for setup instructions.
### 5. Verify
Ask Claude Code to check the connection:
```
> check my spotify connection status
```
The agent will run `status` and confirm authentication is working.
## Architecture
```
You ──→ Claude Code ──→ SKILL.md (musical reasoning framework)
│
├── Spotify Web API
│ playlists, search, playback, listening history
│
├── ReccoBeats API
│ recommendations, audio features
│
└── MusicBrainz API
genre data (cached 30 days)
```
The skill file (`SKILL.md`) isn't just API documentation — it's a reasoning framework that teaches the agent how to think about music. It includes a musical vocabulary, a 6-step workflow for non-trivial requests, a diagnostic table for when recommendations miss the mark, and guardrails for playlist modification.
## Spotify API status (March 2026)
This project works around several Spotify Web API regressions:
| Endpoint | Status | Workaround |
|---|---|---|
| `GET /recommendations` | Removed | ReccoBeats + fallback chain |
| `GET /audio-features` | Removed | ReccoBeats audio features |
| `GET /artists/{id}/related-artists` | Removed | Collaborator discovery via ReccoBeats |
| `GET /artists/{id}/top-tracks` | 403 | Search-based fallback |
| `GET /artists?ids=` (batch) | 403 | Individual artist requests |
| `GET /search` limit | Capped at 10 | Automatic clamping |
See [`references/implementation-notes.md`](references/implementation-notes.md) for full details on each regression and workaround.
## License
MIT