mop-skills/skills/spotify/SKILL.md

name, description

name	description
spotify	Full Spotify music intelligence, catalog search, playback control, playlist curation, party queueing, and personal listening history. Use when the user asks to search for music/podcasts/audiobooks, control Spotify playback, queue tracks, check what is currently playing, create or curate playlists (including collaborative mixes for friends), or inspect listening history and top tracks.

🎵 Spotify Skill for OpenClaw

Full integration with the Spotify Web API powered by mcp-server-spotify.

🛠️ MCP Tools & Capabilities

You have access to 35+ dedicated Spotify MCP tools:

1. Catalog Search

• search(query, types, limit): Search for tracks, artists, albums, playlists, shows, episodes, or audiobooks.
  • types: array containing "track", "artist", "album", "playlist", "show", "episode", "audiobook".
  • Returns Spotify URIs (spotify:track:...), titles, artist names, album info, and web URLs (https://open.spotify.com/...).

2. Playback & Device Control

• get_playback_state(): Returns current player status, active device, shuffle/repeat states, and track progress.
• get_currently_playing(): Quick status of the currently playing track or episode.
• play(device_id, context_uri, uris, position_ms): Start or resume playback. Can play a specific playlist/album URI (context_uri) or a list of track URIs (uris).
• pause(device_id): Pause active playback.
• next_track(device_id) / previous_track(device_id): Skip tracks.
• seek(position_ms, device_id): Seek to a position in milliseconds.
• set_volume(volume_percent, device_id): Set volume (0-100).
• toggle_shuffle(state, device_id): Enable or disable shuffle.
• transfer_playback(device_ids, play): Transfer active playback to another Spotify Connect device.
• get_devices(): List available Spotify Connect devices (TVs, laptops, speakers, mobile).
• add_to_queue(uri, device_id): Add a track/episode URI to the user's active playback queue.
• get_queue(): Inspect currently playing item and upcoming queued items.

3. Playlists & Collaboration

• create_playlist(name, description, public): Create a new Spotify playlist for the user.
• get_playlist(playlist_id): Retrieve playlist metadata and owner.
• get_playlist_items(playlist_id, limit, offset): List tracks inside a playlist.
• add_playlist_items(playlist_id, uris, position): Add track URIs to an existing playlist (supports batch addition).
• remove_playlist_items(playlist_id, uris): Remove tracks from a playlist.
• reorder_playlist_items(playlist_id, range_start, insert_before): Reorder songs in a playlist.
• get_my_playlists(limit, offset): List current user's saved and created playlists.

4. Personal History, Taste & Social

• get_recently_played(limit): History of recently played tracks with timestamps.
• get_my_top_items(type, time_range, limit): Fetch top tracks or top artists over short ("short_term" = 4 weeks), medium ("medium_term" = 6 months), or long term ("long_term" = years).
• get_my_profile(): User's profile details and country.
• whoami(): Diagnostic helper returning authentication state, active device, and granted scopes.

---

📱 Telegram Presentation Guidelines

When formatting Spotify results or music recommendations for Telegram:

• Clean Markdown Links: Always format track and playlist links nicely:
  • ▶️ [Track Title - Artist Name](https://open.spotify.com/track/...)
  • 📁 [Playlist Name](https://open.spotify.com/playlist/...)
• Current Playing Card: When asked "what's playing?":
  • Display: 🎶 *Track Title* by *Artist*\n💿 *Album Title* (Year)\n⏱️ mm:ss / mm:ss [■■■□□□□□□□]\n🔗 [Open in Spotify](url)
• Friend Requests / Party Aux DJ:
  • When a friend in a Telegram group asks to add a song:
    1. Search Spotify for the best match via search.
    2. Add to active queue (add_to_queue) or the group's party playlist (add_playlist_items).
    3. Confirm with a friendly message: "Added 🎵 Song - Artist to the queue! Next up."

---

🏡 Home Assistant (Sonos & Hue) Synergy

OpenClaw has access to both Spotify MCP and Home Assistant MCP (ha-mcp):

• Spotify MCP is the Music Brain: Use it to search the global catalog, find Spotify URIs, build playlists, and inspect listening history.
• Home Assistant is the Physical Hardware Controller:
  • Home Assistant's media_player.play_media requires a Spotify URI (spotify:track:..., spotify:playlist:...).
  • When asked to "Play X in the living room / on Sonos":
    1. Use search from Spotify MCP to get the exact spotify:track:... or spotify:playlist:... URI.
    2. Call ha-mcp:ha_call_service:
       • Domain: media_player
       • Service: play_media
       • Service Data: {"media_content_id": "<spotify_uri>", "media_content_type": "music"}
       • Target: {"entity_id": "media_player.sonos_..."}
    3. If asked for ambience or party lighting, call ha-mcp:ha_call_service on light.turn_on or activate Hue scenes simultaneously.