# Send statsfm 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. 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. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "statsfm", "name": "statsfm", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/space0mel/statsfm", "canonicalUrl": "https://clawhub.ai/space0mel/statsfm", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/statsfm", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=statsfm", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md", "scripts/statsfm.py", "references/api.md" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "statsfm", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-12T18:00:38.923Z", "expiresAt": "2026-05-19T18:00:38.923Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=statsfm", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=statsfm", "contentDisposition": "attachment; filename=\"statsfm-2.6.1.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "statsfm" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/statsfm" }, "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/statsfm", "downloadUrl": "https://openagent3.xyz/downloads/statsfm", "agentUrl": "https://openagent3.xyz/skills/statsfm/agent", "manifestUrl": "https://openagent3.xyz/skills/statsfm/agent.json", "briefUrl": "https://openagent3.xyz/skills/statsfm/agent.md" } } ``` ## Documentation ### stats.fm CLI Comprehensive Python CLI for querying stats.fm API (Spotify listening analytics). Requirements: Python 3.6+ (stdlib only, no pip installs needed) Script location: scripts/statsfm.py in this skill's directory. Examples use ./statsfm.py assuming you're in the scripts folder. ### Prerequisites Stats.fm account (optional) A stats.fm account is only needed for personal listening data (history, top tracks, now playing, etc.) Without an account, you can still use public features: album tracklists, artist discographies, search, and global charts Don't have one? Visit stats.fm and sign up with Spotify or Apple Music (AM untested, Plus status unknown) Already have one? Copy your username from your profile ### Setup No account needed for public commands: search, album, artist-albums, charts-top-tracks, charts-top-artists, charts-top-albums. For personal stats (profile, top-artists, top-tracks, recent, np, etc.), pass your username with --user USERNAME / -u USERNAME. These commands exit with code 1 if no user is provided. ### Quick Start # View your profile ./statsfm.py profile # Top tracks this month ./statsfm.py top-tracks --limit 10 # Track stats for 2025 ./statsfm.py track-stats 188745898 --start 2025 --end 2026 ### User Profile profile - Show username, pronouns, bio, Plus status, timezone, Spotify sync info ### Top Lists top-tracks - Your most played tracks top-artists - Your most played artists top-albums - Your most played albums top-genres - Your top music genres ### Current Activity now-playing (aliases: now, np) - Currently playing track recent - Recently played tracks ### Detailed Stats artist-stats - Your play count, listening time, and monthly breakdown for this artist track-stats - Your play count, listening time, and monthly breakdown for this track (shows track name + album) album-stats - Your play count, listening time, and monthly breakdown for this album stream-stats - Your overall streaming summary (total streams, total time, avg track length, shortest/longest, unique counts for tracks/artists/albums) ### Lookups artist - Artist info and discography. Shows genres, followers, popularity score (100 = very popular, 50 = underground, 0 = no data). --type album|single|all (default: all) --limit N - Items per section (default: 15) album - Album info and full tracklist (release date, label, genres, tracks with duration and [E] tags) artist-albums - All albums/singles by artist, grouped by type (Albums, Singles & EPs, Compilations), newest first. Deduped by ID, 15 per section by default, shows "(N more)" overflow. --type album|single|all (default: all) --limit N - Items per section ### Drill-Down top-tracks-from-artist - Your most played tracks from this artist top-tracks-from-album - Your most played tracks from this album top-albums-from-artist - Your most played albums from this artist ### Global Charts charts-top-tracks - Global top tracks chart charts-top-artists - Global top artists chart charts-top-albums - Global top albums chart ### Search search - Search for artists, tracks, or albums. Use --type artist|track|album to filter results to one category ### Date Ranges All stats commands support both predefined ranges and custom dates: Predefined ranges: --range today or --range 1d - Today only --range 4w - Last 4 weeks (default) --range 6m - Last 6 months --range all - All time (lifetime) Duration ranges (resolved to custom timestamps): --range 7d - Last 7 days --range 14d - Last 14 days --range 30d - Last 30 days --range 90d - Last 90 days Custom date ranges: --start YYYY - Start year (e.g., --start 2025) --start YYYY-MM - Start month (e.g., --start 2025-07) --start YYYY-MM-DD - Start date (e.g., --start 2025-07-15) --end YYYY[-MM[-DD]] - End date (same formats) Examples: # All of 2025 ./statsfm.py top-artists --start 2025 --end 2026 # Just July 2025 ./statsfm.py top-tracks --start 2025-07 --end 2025-08 # Q1 2025 ./statsfm.py artist-stats 39118 --start 2025-01-01 --end 2025-03-31 ### Granularity --granularity monthly - Monthly breakdown (default) --granularity weekly - Weekly breakdown (shows week number + start date) --granularity daily - Daily breakdown (shows date + day name) Works with artist-stats, track-stats, album-stats ### Other Flags --limit N / -l N - Limit results (default: 15) --user USERNAME / -u USERNAME - Specify the stats.fm username to query --no-album - Hide album names in track listings (albums show by default) ### Usage Examples # Search for an artist, then drill down ./statsfm.py search "madison beer" --type artist ./statsfm.py artist-stats 39118 --start 2025 ./statsfm.py top-tracks-from-artist 39118 --limit 20 # Weekly breakdown of a track ./statsfm.py track-stats 188745898 --start 2025 --end 2026 --granularity weekly # Custom date range ./statsfm.py top-artists --start 2025-06 --end 2025-09 # Album tracklist and discography ./statsfm.py album 1365235 ./statsfm.py artist-albums 39118 --type album # Global charts ./statsfm.py charts-top-tracks --limit 20 ### Automatic Monthly Breakdowns Stats commands (artist-stats, track-stats, album-stats) automatically show: Total plays and listening time Monthly breakdown with plays and time per month Works for both predefined ranges and custom date ranges Example output: Total: 505 plays (29h 53m) Monthly breakdown: 2025-02: 67 plays (3h 52m) 2025-03: 106 plays (6h 21m) 2025-04: 40 plays (2h 24m) ... ### Display Information Track listings: Show position, track name, artist, album (by default), play count, time Album listings: Show position, album name, artist, play count, time Artist listings: Show position, artist name, play count, time, genres Charts: Show global rankings with stream counts Recent streams: Show timestamp, track, artist, album (by default) ### Plus vs Free Users Stats.fm Plus required for: Stream counts in top lists Listening time (play duration) Detailed statistics Free users get: Rankings/positions Track/artist/album names Currently playing Search functionality Monthly breakdowns (via per-day stats endpoint) The script handles both gracefully, showing [Plus required] for missing data. ### API Information Base URL: https://api.stats.fm/api/v1 Authentication: None needed for public profiles Response format: JSON with item (single) or items (list) wrapper Rate limiting: Be reasonable with requests. Avoid more than ~10 calls in rapid succession during deep dives. ### Error Handling All errors print to stderr and exit with code 1. Scenariostderr outputWhat to doNo user setError: No user specified.Pass --user USERNAME flagAPI error (4xx/5xx)API Error (code): messageCheck if user exists, profile is public, or ID is validConnection failureConnection Error: reasonRetry after a moment, check networkEmpty resultsNo error, just no outputUser may be private, or no data for that period — try --range allPlus-only dataShows [Plus required] inlineAcknowledge gracefully, show what's available ### Finding IDs Use search to find artist/track/album IDs: # Find artist ./statsfm.py search "sabrina carpenter" --type artist # Returns: [22369] Sabrina Carpenter [pop] # Find track ./statsfm.py search "espresso" --type track # Returns: [188745898] Espresso by Sabrina Carpenter # Find album ./statsfm.py search "short n sweet" --type album # Returns: [56735245] Short n' Sweet by Sabrina Carpenter Then use the ID numbers in other commands. ### Tips Use custom dates for analysis: --start 2025 --end 2026 to see full year stats Chain discoveries: Search → Get ID → Detailed stats → Drill down Compare periods: Run same command with different date ranges Export data: Pipe output to file for records: ./statsfm.py top-tracks --start 2025 > 2025_top_tracks.txt Albums show by default: Match the stats.fm UI behavior (album art is prominent) Monthly breakdowns: All stats commands show month-by-month progression automatically ### For AI Agents Setup: Check memory for a stats.fm username. If missing, ask. All personal data commands need --user USERNAME. Multiple time ranges: Always compare multiple ranges (--range today, 7d, 30d, 90d, all) to show how taste shifts over time. Lifetime stats alone miss current trends. ### Time Translations "This year" → --start 2025 --end 2026 "Last summer" → --start 2025-06 --end 2025-09 "When did I discover X" → artist-stats --range all (first month in breakdown) ### Command Reference IntentCommandKey flagsYour plays of a tracktrack-stats --start/--end, --granularityYour plays of an artistartist-stats --start/--end, --granularityYour plays of an albumalbum-stats --start/--end, --granularityYour overall statsstream-stats--range, --start/--endYour rankingstop-tracks, top-artists, top-albums, top-genres--range, --start/--end, --limitCurrently playingnow-playingRecent tracksrecent--limitArtist overviewartist --limitArtist's discographyartist-albums --limitAlbum tracklistalbum Your top tracks by artisttop-tracks-from-artist --range, --limitYour top tracks on albumtop-tracks-from-album --range, --limitYour top albums by artisttop-albums-from-artist --range, --limitGlobal chartscharts-top-tracks, charts-top-artists, charts-top-albums--range, --limitFind IDssearch --type artist|track|album ### Edge Cases Free users: Play counts are not available for top tracks — rankings and breakdowns still work, lead with those Empty results: Try --range all as fallback. Could also be a private profile. Search duplicates: Use the first result Apple Music: Untested, may have gaps ### References Github Repo: statsfm/statsfm-cli API Endpoints: references/api.md Official JS Client: statsfm/statsfm.js ## Trust - Source: tencent - Verification: Indexed source record - Publisher: space0mel - Version: 2.5.2 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-05-12T18:00:38.923Z - Expires at: 2026-05-19T18:00:38.923Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/statsfm) - [Send to Agent page](https://openagent3.xyz/skills/statsfm/agent) - [JSON manifest](https://openagent3.xyz/skills/statsfm/agent.json) - [Markdown brief](https://openagent3.xyz/skills/statsfm/agent.md) - [Download page](https://openagent3.xyz/downloads/statsfm)