{
  "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": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/spotify-history",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=spotify-history",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "scripts/setup.sh",
      "scripts/spotify-api.py",
      "scripts/spotify-auth.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "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."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "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."
        },
        {
          "label": "Upgrade existing",
          "body": "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."
        }
      ]
    },
    "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."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/spotify-history",
    "agentPageUrl": "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"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "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."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "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."
      },
      {
        "label": "Upgrade existing",
        "body": "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."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Spotify History & Recommendations",
        "body": "Access Spotify listening history and get personalized recommendations."
      },
      {
        "title": "Quick Setup (Recommended)",
        "body": "Run the setup wizard:\n\nbash skills/spotify-history/scripts/setup.sh\n\nThis guides you through:\n\nCreating a Spotify Developer App\nSaving credentials securely\nAuthorizing access"
      },
      {
        "title": "Manual Setup",
        "body": "Create Spotify Developer App\n\nGo to developer.spotify.com/dashboard\nClick Create App\nFill in:\n\nApp name: Clawd (or any name)\nApp description: Personal assistant integration\nRedirect URI: http://127.0.0.1:8888/callback ⚠️ Use exact URL!\n\n\nSave and copy Client ID and Client Secret\n\n\n\nStore Credentials\nOption A: Credentials file (recommended)\nmkdir -p credentials\ncat > credentials/spotify.json <<EOF\n{\n  \"client_id\": \"your_client_id\",\n  \"client_secret\": \"your_client_secret\"\n}\nEOF\nchmod 600 credentials/spotify.json\n\nOption B: Environment variables\n# Add to ~/.zshrc or ~/.bashrc\nexport SPOTIFY_CLIENT_ID=\"your_client_id\"\nexport SPOTIFY_CLIENT_SECRET=\"your_client_secret\"\n\n\n\nAuthenticate\nWith browser (local machine):\npython3 scripts/spotify-auth.py\n\nHeadless (no browser):\npython3 scripts/spotify-auth.py --headless\n\nFollow the prompts to authorize via URL and paste the callback.\n\nTokens are saved to ~/.config/spotify-clawd/token.json and auto-refresh when expired."
      },
      {
        "title": "Command Line",
        "body": "# Recent listening history\npython3 scripts/spotify-api.py recent\n\n# Top artists (time_range: short_term, medium_term, long_term)\npython3 scripts/spotify-api.py top-artists medium_term\n\n# Top tracks\npython3 scripts/spotify-api.py top-tracks medium_term\n\n# Get recommendations based on your top artists\npython3 scripts/spotify-api.py recommend\n\n# Raw API call (any endpoint)\npython3 scripts/spotify-api.py json /me\npython3 scripts/spotify-api.py json /me/player/recently-played"
      },
      {
        "title": "Time Ranges",
        "body": "short_term — approximately last 4 weeks\nmedium_term — approximately last 6 months (default)\nlong_term — all time"
      },
      {
        "title": "Example Output",
        "body": "Top Artists (medium_term):\n  1. Hans Zimmer [soundtrack, score]\n  2. John Williams [soundtrack, score]\n  3. Michael Giacchino [soundtrack, score]\n  4. Max Richter [ambient, modern classical]\n  5. Ludovico Einaudi [italian contemporary classical]"
      },
      {
        "title": "Agent Usage",
        "body": "When user asks about music:\n\n\"What have I been listening to?\" → spotify-api.py recent\n\"Who are my top artists?\" → spotify-api.py top-artists\n\"Recommend new music\" → spotify-api.py recommend + add your own knowledge\n\nFor recommendations, combine API data with music knowledge to suggest similar artists not in their library."
      },
      {
        "title": "\"Spotify credentials not found!\"",
        "body": "Make sure credentials/spotify.json exists or environment variables are set\nCredential file is checked first, then env vars\nRun bash skills/spotify-history/scripts/setup.sh to create credentials"
      },
      {
        "title": "\"Not authenticated. Run spotify-auth.py first.\"",
        "body": "Tokens don't exist or are invalid\nRun: python3 scripts/spotify-auth.py (or with --headless if no browser)"
      },
      {
        "title": "\"HTTP Error 400: Bad Request\" during token refresh",
        "body": "Credentials changed or are invalid\nRe-run setup: bash skills/spotify-history/scripts/setup.sh\nOr update credentials/spotify.json with correct Client ID/Secret"
      },
      {
        "title": "\"HTTP Error 401: Unauthorized\"",
        "body": "Token expired and auto-refresh failed\nDelete token and re-authenticate:\nrm ~/.config/spotify-clawd/token.json\npython3 scripts/spotify-auth.py"
      },
      {
        "title": "Headless / No Browser",
        "body": "Use --headless flag: python3 scripts/spotify-auth.py --headless\nManually open the auth URL on any device\nCopy the callback URL (starts with http://127.0.0.1:8888/callback?code=...)\nPaste it back when prompted"
      },
      {
        "title": "Security Notes",
        "body": "Tokens stored with 0600 permissions (user-only read/write)\nClient secret should be kept private\nRedirect URI uses 127.0.0.1 (local only) for security"
      },
      {
        "title": "Required Scopes",
        "body": "user-read-recently-played — recent listening history\nuser-top-read — top artists and tracks\nuser-read-playback-state — current playback\nuser-read-currently-playing — currently playing track"
      }
    ],
    "body": "Spotify History & Recommendations\n\nAccess Spotify listening history and get personalized recommendations.\n\nSetup (One-Time)\nQuick Setup (Recommended)\n\nRun the setup wizard:\n\nbash skills/spotify-history/scripts/setup.sh\n\n\nThis guides you through:\n\nCreating a Spotify Developer App\nSaving credentials securely\nAuthorizing access\nManual Setup\n\nCreate Spotify Developer App\n\nGo to developer.spotify.com/dashboard\nClick Create App\nFill in:\nApp name: Clawd (or any name)\nApp description: Personal assistant integration\nRedirect URI: http://127.0.0.1:8888/callback ⚠️ Use exact URL!\nSave and copy Client ID and Client Secret\n\nStore Credentials\n\nOption A: Credentials file (recommended)\n\nmkdir -p credentials\ncat > credentials/spotify.json <<EOF\n{\n  \"client_id\": \"your_client_id\",\n  \"client_secret\": \"your_client_secret\"\n}\nEOF\nchmod 600 credentials/spotify.json\n\n\nOption B: Environment variables\n\n# Add to ~/.zshrc or ~/.bashrc\nexport SPOTIFY_CLIENT_ID=\"your_client_id\"\nexport SPOTIFY_CLIENT_SECRET=\"your_client_secret\"\n\n\nAuthenticate\n\nWith browser (local machine):\n\npython3 scripts/spotify-auth.py\n\n\nHeadless (no browser):\n\npython3 scripts/spotify-auth.py --headless\n\n\nFollow the prompts to authorize via URL and paste the callback.\n\nTokens are saved to ~/.config/spotify-clawd/token.json and auto-refresh when expired.\n\nUsage\nCommand Line\n# Recent listening history\npython3 scripts/spotify-api.py recent\n\n# Top artists (time_range: short_term, medium_term, long_term)\npython3 scripts/spotify-api.py top-artists medium_term\n\n# Top tracks\npython3 scripts/spotify-api.py top-tracks medium_term\n\n# Get recommendations based on your top artists\npython3 scripts/spotify-api.py recommend\n\n# Raw API call (any endpoint)\npython3 scripts/spotify-api.py json /me\npython3 scripts/spotify-api.py json /me/player/recently-played\n\nTime Ranges\nshort_term — approximately last 4 weeks\nmedium_term — approximately last 6 months (default)\nlong_term — all time\nExample Output\nTop Artists (medium_term):\n  1. Hans Zimmer [soundtrack, score]\n  2. John Williams [soundtrack, score]\n  3. Michael Giacchino [soundtrack, score]\n  4. Max Richter [ambient, modern classical]\n  5. Ludovico Einaudi [italian contemporary classical]\n\nAgent Usage\n\nWhen user asks about music:\n\n\"What have I been listening to?\" → spotify-api.py recent\n\"Who are my top artists?\" → spotify-api.py top-artists\n\"Recommend new music\" → spotify-api.py recommend + add your own knowledge\n\nFor recommendations, combine API data with music knowledge to suggest similar artists not in their library.\n\nTroubleshooting\n\"Spotify credentials not found!\"\nMake sure credentials/spotify.json exists or environment variables are set\nCredential file is checked first, then env vars\nRun bash skills/spotify-history/scripts/setup.sh to create credentials\n\"Not authenticated. Run spotify-auth.py first.\"\nTokens don't exist or are invalid\nRun: python3 scripts/spotify-auth.py (or with --headless if no browser)\n\"HTTP Error 400: Bad Request\" during token refresh\nCredentials changed or are invalid\nRe-run setup: bash skills/spotify-history/scripts/setup.sh\nOr update credentials/spotify.json with correct Client ID/Secret\n\"HTTP Error 401: Unauthorized\"\nToken expired and auto-refresh failed\nDelete token and re-authenticate:\nrm ~/.config/spotify-clawd/token.json\npython3 scripts/spotify-auth.py\n\nHeadless / No Browser\nUse --headless flag: python3 scripts/spotify-auth.py --headless\nManually open the auth URL on any device\nCopy the callback URL (starts with http://127.0.0.1:8888/callback?code=...)\nPaste it back when prompted\nSecurity Notes\nTokens stored with 0600 permissions (user-only read/write)\nClient secret should be kept private\nRedirect URI uses 127.0.0.1 (local only) for security\nRequired Scopes\nuser-read-recently-played — recent listening history\nuser-top-read — top artists and tracks\nuser-read-playback-state — current playback\nuser-read-currently-playing — currently playing track"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/braydoncoyer/spotify-history",
    "publisherUrl": "https://clawhub.ai/braydoncoyer/spotify-history",
    "owner": "braydoncoyer",
    "version": "1.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "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"
  }
}