magnus919_agent-skills/lastfm/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
lastfm	Interact with the Last.fm music data API: lookup user listening history, get artist/album/track metadata, discover similar music via collaborative filtering, explore global and per-country charts, search by artist/album/track, manage tags, and scrobble listening events. Use when the user asks about music data, listening statistics, music recommendations, similar artists, charts, or wants to scrobble or love tracks. Do not use this skill for unrelated requests; route to the nearest named specialist.	MIT	Requires a Last.fm API key in the LASTFM_API_KEY env var. For write operations (scrobble, love, now-playing), also needs LASTFM_API_SECRET and LASTFM_SESSION_KEY. The `lastfm-cli` CLI tool must be on PATH.	tags source music, lastfm, scrobbling, api-client, music-discovery https://www.last.fm/api

Last.fm

Setup

export LASTFM_API_KEY="your_api_key_here"
# For write operations only:
export LASTFM_API_SECRET="your_api_secret"
export LASTFM_SESSION_KEY="your_session_key"

Get an API key at https://www.last.fm/api/account/create (free, requires a Last.fm account).

Essential Commands

User queries — "what am I listening to"

Configurable via LASTFM_USERNAME env var. Defaults to <username> if unset.

lastfm-cli user info <username>                      # Profile + stats
lastfm-cli user recent-tracks <username> --limit 10   # Recent listening
lastfm-cli user top-artists <username> --period 7day  # Weekly top artists
lastfm-cli user top-tracks <username> --period overall # All-time faves
lastfm-cli user loved-tracks <username>               # Loved tracks
lastfm-cli user friends <username>                    # Social graph
lastfm-cli user weekly-charts <username>              # Available chart periods

Music Discovery — "what's similar to X"

lastfm-cli artist similar <artist> --limit 10         # Taste graph neighbors
lastfm-cli artist info <artist>                       # Bio, stats, tags
lastfm-cli artist top-tracks <artist>                 # Their most popular
lastfm-cli track similar <artist> "<track>"           # Track-level similarity
lastfm-cli album info <artist> "<album>"              # Tracklist, metadata
lastfm-cli tag top-artists <tag>                      # Genre browsing

Charts — "what's popular"

lastfm-cli chart top-artists --limit 20               # Global
lastfm-cli geo top-artists "Japan" --limit 20         # Per-country
lastfm-cli geo top-tracks "Germany" --limit 20
lastfm-cli tag top-tracks "electronic" --limit 15     # By genre tag

Search — "find that thing"

lastfm-cli artist search "Radiohead"                  # Find by name
lastfm-cli album search "OK Computer"                 # Find albums
lastfm-cli track search "Karma Police"                # Find tracks

Write operations (require session auth)

lastfm-cli track scrobble "Artist" "Song" --album "Album"
lastfm-cli track now-playing "Artist" "Song"
lastfm-cli track love "Artist" "Song"

Auth flow (one-time setup)

# 1. Get a token
lastfm-cli auth get-token

# 2. User visits: https://www.last.fm/api/auth/?api_key=KEY&token=TOKEN

# 3. Exchange for session key
lastfm-cli auth get-session <token>
# → Set export LASTFM_SESSION_KEY=<key>

Reference Files

• references/auth-flow.md — Full walkthrough for setting up write operation auth (scrobble, love, now-playing). Read this before attempting write operations.

Music Discovery Pipeline — "find me new stuff I'll like"

The core flow for turning liked tracks into recommendations:

1. Get user's top artists/tracks from Last.fm:

   lastfm-cli user top-artists <username> --period 1month --limit 5 --json
   lastfm-cli user top-tracks <username> --period 1month --limit 10 --json
   lastfm-cli user loved-tracks <username> --json
   

2. For each artist, find similar artists via Last.fm's collaborative filtering:

   lastfm-cli artist similar "<artist>" --limit 5 --json
   

3. For each track, find similar tracks for more granular recommendations:

   lastfm-cli track similar "<artist>" "<track>" --limit 5 --json
   

4. Cross-reference against what they've already scrobbled (recent-tracks) to filter out already-heard material.

5. Check against the user's own collection (via Radarr/Sonarr/jellyfin or Spotify library) to see what's already in the library vs genuinely new discovery.

Using with --json for Machine Processing

# Pipe to jq for structured queries
lastfm-cli artist similar "Radiohead" --limit 5 --json | jq '.similarartists.artist[] | {name, match}'

# Get a user's all-time top artists with playcounts
lastfm-cli user top-artists <username> --period overall --limit 3 --json | jq '.topartists.artist[] | {name, playcount}'

# Find most popular tracks by a genre
lastfm-cli tag top-tracks "electronic" --limit 10 --json | jq '.tracks.track[] | {name, artist: .artist.name, listeners}'

Known Gotchas

• API key required for EVERY request. The key is free — get one at the Last.fm API account page.
• Rate limit is ~5 req/sec sustained. The API docs say "be reasonable" — if you're making several calls per second continuously, your account may be suspended. Add small delays in loops.
• User-Agent header matters. The CLI sends lastfm-cli/1.0 (hermes-agent). Last.fm's docs explicitly ask for an identifiable User-Agent.
• XML is the default response format. The CLI requests format=json. Without it, responses come back as XML.
• Artist names can be misspelled. Use --autocorrect flag on artist commands to let Last.fm correct misspellings.
• Write operations need auth setup. scrobble, love, and now-playing require a full auth flow (token → session key). Read-only endpoints don't.
• The collaborative filtering graph is NOT social. artist.getSimilar returns algorithmic similarity based on aggregate listening patterns, not human-curated recommendations.
• Timestamps for scrobbles are UNIX epoch seconds. If omitted, uses current time.
• --from and --to on recent-tracks accept ISO 8601 date strings (e.g., 2026-05-27).
• Period values: overall, 7day, 1month, 3month, 6month, 12month.

When to Reach for This Tool

• User asks "what's [person] listening to lately?"
• User wants music discovery: "find me artists similar to..."
• User wants listening statistics: top artists, tracks, albums by period
• User wants geographic music trends: "what's popular in [country]"
• User wants genre exploration via tags
• User wants to scrobble or love tracks programmatically
• Any question about music metadata, artist info, album tracklists

Available Scripts

Script	Purpose	Invocation
scripts/lastfm-cli	The CLI tool this skill drives: read-only queries (user info/recent-tracks/top-artists/top-tracks/loved-tracks/friends/weekly-charts), discovery (artist similar, track similar), charts and geo charts, search, tags, and — with session auth — scrobble, now-playing, and love. Run it for every Last.fm data question above; see Essential Commands for the full command surface.	scripts/lastfm-cli user top-artists <username> --period 7day --limit 10
scripts/test-lastfm.sh	Shell test suite covering the CLI's argument handling and output formatting without network calls. Run it after modifying scripts/lastfm-cli or when auditing a change to its behavior; CI runs it via scripts/check-skill-tests.py.	bash scripts/test-lastfm.sh

Prerequisites

• A free Last.fm API key exported as LASTFM_API_KEY (create one at https://www.last.fm/api/account/create); every request fails without it.
• For write operations only: LASTFM_API_SECRET plus a session key from the one-time auth flow in references/auth-flow.md, exported as LASTFM_SESSION_KEY.
• Python 3 on PATH — invoke the bundled tool as python3 scripts/lastfm-cli ... if it is not executable directly; the SKILL.md examples assume lastfm-cli resolves on PATH.
• Optional: LASTFM_USERNAME to set the default user for user queries; jq when piping --json output for structured processing.

Limitations

• Read-only endpoints need only the API key; scrobble, now-playing, and love require the full token → session-key auth flow and will fail without it.
• Sustained call rates above ~5 req/sec risk account suspension — add small delays in loops.
• Similarity endpoints are algorithmic collaborative filtering over aggregate listening patterns, not social or human-curated recommendations.
• Period values are fixed to overall, 7day, 1month, 3month, 6month, and 12month; arbitrary date ranges are only available via --from/--to on recent-tracks.
• Misspelled artist names return empty or wrong results unless --autocorrect is used.

When not to use

Do not use this skill for music playback control (local players, streaming queues), for non-Last.fm catalog data (MusicBrainz, Spotify metadata), or as a lyrics source — the API covers listening history, metadata, charts, tags, similarity, and scrobbling only.