Execution Model
This skill runs directly via local Python scripts.
Valid entrypoints:
python run_pipeline.py ...python auth.py
Absolute rules
- Do NOT use ACP
- Do NOT request or require an agentId
- Do NOT propose manual workflows
- Do NOT suggest alternative scripts or paths
- Do NOT reference any
scripts/ directory
- Do NOT use
python -m module execution
- Do NOT assume the package must be installed
All commands must be executed from the root of this skill folder.
Critical Behavior Rules
If the user asks for:
- creating a playlist
- adding songs to Spotify
- saving results to Spotify
You MUST execute:
--output-mode spotify --create-playlist
Primary entrypoints:
- `python run_pipeline.py ...`
- `python auth.py ...`
This skill is intentionally organized as plain scripts plus helper modules:
- `run_pipeline.py`
- `auth.py`
- `lastfm.py`
- `spotify.py`
- `pipeline.py`
- `common.py`
No package installation is required.
# Purpose
This skill:
- uses Last.fm as the discovery engine
- expands seeds through `track.getsimilar`
- ranks merged candidates
- optionally matches results on Spotify
- optionally creates Spotify playlists
# Requirements
## Python
A normal local Python interpreter must be available.
## Last.fm credentials
Supported sources:
- environment variables:
- `LASTFM_API_KEY`
- `LASTFM_SHARED_SECRET`
- `LASTFM_USERNAME`
- credentials file:
- `~/.openclaw/lastfm-credentials.json`
- explicit file path via command flag:
- `--creds <path>`
Example file:
```json
{
"api_key": "YOUR_LASTFM_API_KEY",
"shared_secret": "YOUR_LASTFM_SHARED_SECRET",
"username": "YOUR_LASTFM_USERNAME"
}
Spotify credentials
Needed only for Spotify matching or playlist creation.
Supported sources:
- environment variables:
SPOTIFY_CLIENT_IDSPOTIFY_CLIENT_SECRETSPOTIFY_REDIRECT_URI
- credentials file:
~/.openclaw/spotify-credentials.json
- explicit file path via command flag:
Saved token location:
~/.openclaw/spotify-token.json- or explicit path via
--spotify-token <path>
Command Selection
1. Recommend from recent Last.fm listening
Use when the request is based on a user's recent scrobbles.
python run_pipeline.py recent-tracks --user "<LASTFM_USER>" --recent-count 10 --similar-per-seed 5 --final-limit 20 --output-mode lastfm-only
2. Recommend from a seed artist
Use when the request is based on one artist.
python run_pipeline.py artist-rule-c "<ARTIST_NAME>" --seed-count 5 --similar-per-seed 10 --final-limit 20 --output-mode lastfm-only
3. Recommend from top artists
Use when the request is based on a user's broader taste profile.
python run_pipeline.py top-artists-blend --user "<LASTFM_USER>" --period 1month --artist-count 5 --seed-count-per-artist 3 --similar-per-seed 5 --final-limit 20 --output-mode lastfm-only
4. Match recommendations to Spotify
Use when the user wants playable Spotify results but not necessarily a playlist.
python run_pipeline.py recent-tracks --user "<LASTFM_USER>" --recent-count 10 --final-limit 20 --output-mode spotify
5. Create Spotify playlist
Use when the user explicitly wants a playlist created.
python run_pipeline.py recent-tracks --user "<LASTFM_USER>" --recent-count 10 --final-limit 20 --output-mode spotify --create-playlist --playlist-name "Last.fm Recommendations"
6. Run Spotify auth
Use when Spotify token setup is required.
python auth.py
Optional explicit paths:
python auth.py --spotify-creds "<PATH_TO_SPOTIFY_CREDS_JSON>" --spotify-token "<PATH_TO_SPOTIFY_TOKEN_JSON>"
Behavior Rules
- Prefer Last.fm for recommendation discovery
- Use Spotify only for:
- search
- playlist creation
- playlist population
- If the user only wants suggestions, use
--output-mode lastfm-only
- If the user wants Spotify results, use
--output-mode spotify
- If the user wants a playlist created, add
--create-playlist
- Never invent missing credentials
- Never fall back to ACP or agent execution
Output Expectations
The scripts print JSON to stdout.
Return the JSON result directly or summarize it faithfully.
Typical fields include:
modeuserseed_artistseed_trackssuggestionsmatched_tracksunmatched_tracksplaylist
Error Handling
If the script exits with an error:
- surface stderr or the raised error message directly
- do not retry through ACP
- do not ask for an agentId
- do not claim the skill is unavailable because it is not a package
Common expected failures:
- missing Last.fm API key
- missing Last.fm username
- missing Spotify credentials
- missing Spotify token
- expired Spotify token without refresh token
Notes
This skill is intentionally script-based for reliability.
It should work as long as:
- the skill folder is present
- Python is present
- credentials are configured
- commands are executed from the skill folder root
It must not depend on package installation, editable installs, or import path manipulation.
