# Send Spotify History to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "spotify-history",
    "name": "Spotify History",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/braydoncoyer/spotify-history",
    "canonicalUrl": "https://clawhub.ai/braydoncoyer/spotify-history",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/spotify-history",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=spotify-history",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "scripts/setup.sh",
      "scripts/spotify-api.py",
      "scripts/spotify-auth.py"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/spotify-history"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/spotify-history",
    "downloadUrl": "https://openagent3.xyz/downloads/spotify-history",
    "agentUrl": "https://openagent3.xyz/skills/spotify-history/agent",
    "manifestUrl": "https://openagent3.xyz/skills/spotify-history/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/spotify-history/agent.md"
  }
}
```
## Documentation

### Spotify History & Recommendations

Access Spotify listening history and get personalized recommendations.

### Quick Setup (Recommended)

Run the setup wizard:

bash skills/spotify-history/scripts/setup.sh

This guides you through:

Creating a Spotify Developer App
Saving credentials securely
Authorizing access

### Manual Setup

Create Spotify Developer App

Go to developer.spotify.com/dashboard
Click Create App
Fill in:

App name: Clawd (or any name)
App description: Personal assistant integration
Redirect URI: http://127.0.0.1:8888/callback ⚠️ Use exact URL!


Save and copy Client ID and Client Secret



Store Credentials
Option A: Credentials file (recommended)
mkdir -p credentials
cat > credentials/spotify.json <<EOF
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}
EOF
chmod 600 credentials/spotify.json

Option B: Environment variables
# Add to ~/.zshrc or ~/.bashrc
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"



Authenticate
With browser (local machine):
python3 scripts/spotify-auth.py

Headless (no browser):
python3 scripts/spotify-auth.py --headless

Follow the prompts to authorize via URL and paste the callback.

Tokens are saved to ~/.config/spotify-clawd/token.json and auto-refresh when expired.

### Command Line

# Recent listening history
python3 scripts/spotify-api.py recent

# Top artists (time_range: short_term, medium_term, long_term)
python3 scripts/spotify-api.py top-artists medium_term

# Top tracks
python3 scripts/spotify-api.py top-tracks medium_term

# Get recommendations based on your top artists
python3 scripts/spotify-api.py recommend

# Raw API call (any endpoint)
python3 scripts/spotify-api.py json /me
python3 scripts/spotify-api.py json /me/player/recently-played

### Time Ranges

short_term — approximately last 4 weeks
medium_term — approximately last 6 months (default)
long_term — all time

### Example Output

Top Artists (medium_term):
  1. Hans Zimmer [soundtrack, score]
  2. John Williams [soundtrack, score]
  3. Michael Giacchino [soundtrack, score]
  4. Max Richter [ambient, modern classical]
  5. Ludovico Einaudi [italian contemporary classical]

### Agent Usage

When user asks about music:

"What have I been listening to?" → spotify-api.py recent
"Who are my top artists?" → spotify-api.py top-artists
"Recommend new music" → spotify-api.py recommend + add your own knowledge

For recommendations, combine API data with music knowledge to suggest similar artists not in their library.

### "Spotify credentials not found!"

Make sure credentials/spotify.json exists or environment variables are set
Credential file is checked first, then env vars
Run bash skills/spotify-history/scripts/setup.sh to create credentials

### "Not authenticated. Run spotify-auth.py first."

Tokens don't exist or are invalid
Run: python3 scripts/spotify-auth.py (or with --headless if no browser)

### "HTTP Error 400: Bad Request" during token refresh

Credentials changed or are invalid
Re-run setup: bash skills/spotify-history/scripts/setup.sh
Or update credentials/spotify.json with correct Client ID/Secret

### "HTTP Error 401: Unauthorized"

Token expired and auto-refresh failed
Delete token and re-authenticate:
rm ~/.config/spotify-clawd/token.json
python3 scripts/spotify-auth.py

### Headless / No Browser

Use --headless flag: python3 scripts/spotify-auth.py --headless
Manually open the auth URL on any device
Copy the callback URL (starts with http://127.0.0.1:8888/callback?code=...)
Paste it back when prompted

### Security Notes

Tokens stored with 0600 permissions (user-only read/write)
Client secret should be kept private
Redirect URI uses 127.0.0.1 (local only) for security

### Required Scopes

user-read-recently-played — recent listening history
user-top-read — top artists and tracks
user-read-playback-state — current playback
user-read-currently-playing — currently playing track
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: braydoncoyer
- Version: 1.1.0
## Source health
- Status: healthy
- Source download looks usable.
- Yavira can redirect you to the upstream package for this source.
- Health scope: source
- Reason: direct_download_ok
- Checked at: 2026-05-07T17:22:31.273Z
- Expires at: 2026-05-14T17:22:31.273Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/spotify-history)
- [Send to Agent page](https://openagent3.xyz/skills/spotify-history/agent)
- [JSON manifest](https://openagent3.xyz/skills/spotify-history/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/spotify-history/agent.md)
- [Download page](https://openagent3.xyz/downloads/spotify-history)