Spotify control, in plain language

Tell your AI to play something. It plays it.

Play, pause, skip, set volume, search, play by name, work with playlists and the queue, and move audio between your devices, all by asking in normal words.

Prefers the Spotify Web API and quietly falls back to AppleScript for local transport when the API has no active device or the account is not Premium. Output tagged (this Mac) came from the fallback, so you always know which path answered.

What you need

• Python 3, standard library only. No pip install, no virtualenv, no third-party code. This one is deliberately dependency-free.
• A free Spotify developer app for a Client ID. The Client ID is not a secret, and there is no client secret at any point: auth is PKCE.
• Spotify Premium for playback control. Search and metadata work without it.

Known traps

These are real things that cost time, written down so they cost you none.

• The redirect URI must be exactly http://127.0.0.1:8888/callback. Spotify rejects localhost; the literal 127.0.0.1 is required.
• Tokens are written to ~/.config/claude-spotify/tokens.json with mode 0600 inside a 0700 directory. Nothing is sent anywhere else.
• Scopes are deliberately minimal: read playback state, modify playback state, read private playlists. Library and playlist writes are deliberately not requested, so this cannot alter your saved music even if asked to.

Portability

The Web API path is cross-platform. The AppleScript fallback is macOS only, so on Linux or Windows anything needing local transport requires the API path to be working.

Installing it

This is a folder of markdown instructions plus its helper scripts. Any AI that can read instructions from a file can use it. Pick your tool:

Claude Code

cp -r spotify ~/.claude/skills/

Or drop it in <your-project>/.claude/skills/ to keep it project-local.

Codex, Antigravity, Cursor, or anything else that reads local files

Put the folder anywhere in your project and point your agent at it. In Codex, adding a line to AGENTS.md is enough:

The spotify skill lives in ./spotify. Read spotify/SKILL.md before using it.

Claude.ai or another browser chat

This one runs scripts on your machine, so a browser chat window cannot do much with it. You need a tool with access to your files.

Anything else

SKILL.md is plain markdown with YAML frontmatter (name, description). If your platform rejects unknown frontmatter keys, delete the model: line and it will load.

Before you run it

Do not blindly trust skills you download from the internet, including mine. This one ships scripts that run on your machine. Check it first, which your AI can do in about a minute:

Read every file in this folder, including the scripts. Tell me plainly: does anything
here send my data anywhere, contact the internet, run something I would not expect, or
ask for credentials? Quote the exact lines that made you say so. If it is clean, say so.

If the answer worries you, do not run it.

Where this came from

This is a real working skill, pulled out of a private knowledge vault and anonymised for release. It is not a demo. The Session History section inside SKILL.md keeps the bugs and dead ends found while building it, because those are usually the most useful part.

Licence

MIT. Do what you like with it.

Built by JP Pieterse.