| 1 | --- |
| 2 | name: spotify |
| 3 | description: Control Spotify playback and search the library and playlists. Use when: spotify, music, playlist, play, pause, or what's playing. |
| 4 | invocation: model+user |
| 5 | --- |
| 6 | |
| 7 | # Spotify |
| 8 | |
| 9 | ## When to use |
| 10 | Playing, pausing, skipping, identifying the current track, searching for |
| 11 | music, and reading playlists. |
| 12 | |
| 13 | ## Setup |
| 14 | Two paths: |
| 15 | |
| 16 | 1. **Local control (macOS, no setup).** The Spotify desktop app must be |
| 17 | running, or say so: |
| 18 | `osascript -e 'tell application "Spotify" to playpause'` |
| 19 | 2. **Web API (search, playlists, other platforms).** Requires an authorized Spotify |
| 20 | connection with suitable scopes; report missing access without asking the |
| 21 | user to paste a token into chat: |
| 22 | `GET api.spotify.com/v1/search`, `/v1/me/playlists`, `/v1/playlists/{id}`. |
| 23 | |
| 24 | ## Workflow |
| 25 | 1. Prefer local control for transport (play/pause/next/previous/current track). |
| 26 | Use the requested `play` or `pause` verb; `playpause` is a toggle and cannot |
| 27 | safely be retried after an uncertain result. Verify player state afterward. |
| 28 | 2. Use available Web API endpoints for search and playlist contents. Check |
| 29 | current app-access restrictions; do not promise the restricted Recommendations |
| 30 | API. Handle 403/429 responses without bypassing access or rate limits. |
| 31 | 3. Report artist, track, album, and playlist names verbatim. |
| 32 | |
| 33 | ## Non-goals |
| 34 | - Do not change playlists (add/remove/reorder) unless asked. |
| 35 | - Do not download or rip audio. |
| 36 | - Do not handle the user's Spotify password. |
| 37 | |
| 38 | Reference: [Spotify API changes](https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api). |
| 39 |