steam-gaming-companion

name steam-gaming-companion description Steam & PC Gaming Companion — full Steam Web API integration for library management, play recommendations, wishlist sale monitoring, achievement tracking, and game info lookup. The first real Steam API skill on ClawHub. version 1.0.0 tags ["gaming","steam","pc-gaming","library-management","achievements","wishlist","backlog","recommendations"] author steam-companion requires ["STEAM_API_KEY","STEAM_ID"] optional_env ["IGDB_CLIENT_ID","IGDB_ACCESS_TOKEN"] Steam & PC Gaming Companion A complete Steam Web API integration skill. Manages your library, tracks achievements, monitors wishlist sales, recommends what to play next, and looks up any game — all from natural language. Setup Step 1: Get Your Steam API Key (required, 30 seconds) Go to https://steamcommunity.com/dev/apikey Sign in with your Steam account Enter any domain name (e.g. localhost ) — it doesn't matter for personal use Click Register and copy the key Set it: STEAM_API_KEY=<your-key> Step 2: Get Your 64-bit Steam ID (required, 15 seconds) Your Steam ID is NOT your vanity URL or display name. It's a 17-digit number. Go to https://steamid.io Paste your Steam profile URL (e.g. https://steamcommunity.com/id/yourname ) Copy the steamID64 value (looks like 76561198012345678 ) Set it: STEAM_ID=<your-steam-id-64> Step 3: Get IGDB Credentials (optional, 2 minutes) IGDB provides richer game metadata (ratings, genres, descriptions) than the Steam store API. It's free via Twitch. Go to https://dev.twitch.tv/console/apps and log in with your Twitch account (create one if needed) Click Register Your Application Name: anything (e.g. steam-companion ), OAuth Redirect: http://localhost , Category: Application Integration Click Manage on your new app, copy the Client ID Generate a Client Secret and copy it Get an access token by running: curl -X POST 'https://id.twitch.tv/oauth2/token' \ -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials' Copy the access_token from the response Set both: IGDB_CLIENT_ID=<your-client-id> IGDB_ACCESS_TOKEN=<your-access-token> Note: IGDB tokens expire after ~60 days. If game lookups start failing with 401, regenerate the token using step 6. Step 4: Verify Setup Tell the agent: "verify my steam setup" — it will confirm your credentials work and show your account name and library size. Trigger Conditions User Says (examples) Feature Triggered "show my steam library", "how many games do I own", "what's in my backlog" Library Overview + Backlog Manager "what should I play", "recommend something chill for an hour", "I have all night, what's good" Play Recommender "any wishlist sales", "check my wishlist", "are any of my wishlisted games on sale" Wishlist Sale Monitor "show my achievements for Hades", "how far am I in Elden Ring", "achievement progress" Achievement Tracker "most played games", "what do I play the most", "top 10 games by hours" Most Played Rankings "tell me about Hollow Knight", "look up Baldur's Gate 3", "game info for Celeste" Game Info Lookup "verify my steam setup", "test steam connection", "are my steam credentials working" Setup Verification Feature 1: Library Overview + Backlog Manager API Call GET https://api.steampowered.com/IPlayerService/GetOwnedGames/v1/ Query parameters: Parameter Value key {STEAM_API_KEY} steamid {STEAM_ID} include_appinfo 1 include_played_free_games 1 format json Response Fields Used { "response" : { "game_count" : 247 , "games" : [ { "appid" : 570 , "name" : "Dota 2" , "playtime_forever" : 14523 , "playtime_2weeks" : 120 , "img_icon_url" : "hash" , "has_community_visible_stats" : true } ] } } playtime_forever is in minutes playtime_2weeks is present only if the game was played in the last 2 weeks Logic Rules Categorize every game by playtime_forever : Category Rule Label Unplayed playtime_forever < 60 Never really touched Abandoned 60 <= playtime_forever < 300 Tried but didn't stick Played playtime_forever >= 300 Actually played Response Format 🎮 Steam Library Overview 📊 Total Games: {game_count} ✅ Played (5+ hrs): {played_count} ({played_pct}%) ⚠️ Abandoned (1-5 hrs): {abandoned_count} ({abandoned_pct}%) 🆕 Unplayed (<1 hr): {unplayed_count} ({unplayed_pct}%) ⏱️ Total Lifetime Hours: {total_hours} 📦 Your Backlog ({unplayed_count} games) {for each unplayed game, sorted alphabetically:} • {name} — {playtime_forever} min logged {end} ⚠️ Abandoned Games ({abandoned_count}) {for each abandoned game, sorted by playtime_forever ascending:} • {name} — {hours}h {minutes}m {end} If game_count is 0 or the games array is missing, the profile is likely private. See Error Handling. Feature 2: Play Recommender Prerequisites Fetch the full library using the same API call as Feature 1. Interaction Flow Ask the user two questions (or extract from their message if already stated): Mood : chill / intense / story-driven / competitive Time available : under 1 hour / 1-2 hours / all night (3+ hours) Filter the user's library to games with playtime_forever < 60 (unplayed) OR 60 <= playtime_forever < 300 (abandoned — gave it a short try). For each candidate game, look up genre data. Use one of these methods: If IGDB credentials exist : POST to https://api.igdb.com/v4/games with body search "{game_name}"; fields genres.name, themes.name, total_rating; limit 1; and headers Client-ID: {IGDB_CLIENT_ID} , Authorization: Bearer {IGDB_ACCESS_TOKEN} If no IGDB : GET https://store.steampowered.com/api/appdetails?appids={appid} and extract data.genres[].description and data.short_description Match games to mood using these genre mappings: Mood Matching Genres / Themes Chill Simulation, Puzzle, Casual, Farming, Sandbox, Walking Simulator, Indie (non-horror) Intense Action, Shooter, Roguelike, Roguelite, Survival Horror, Souls-like, Bullet Hell Story-driven RPG, Adventure, Visual Novel, Interactive Fiction, Narrative, Point & Click Competitive Multiplayer, PvP, Fighting, Sports, Racing, Battle Royale, MOBA Match games to time available: Time Slot Rule Under 1 hour Prefer games with short play sessions — roguelites, puzzle games, platformers, arcade. Avoid open-world RPGs or grand strategy. 1-2 hours Any genre works. Prefer games with moderate session lengths. All night Prefer RPGs, open-world, strategy, survival, sandbox — games that reward long sessions. Select the top 3 matches. If fewer than 3 match, relax the playtime filter to include games up to 600 minutes. Response Format 🎯 Play Recommendations — {mood}, {time_available} 1. 🎮 {game_name} Genre: {genres} Why: {1-2 sentence reason based on mood + time fit} Playtime so far: {minutes} min 2. 🎮 {game_name} Genre: {genres} Why: {reason} Playtime so far: {minutes} min 3. 🎮 {game_name} Genre: {genres} Why: {reason} Playtime so far: {minutes} min 💡 None of these click? Tell me more about what you're in the mood for. If no games match at all: 😅 Couldn't find a great match in your unplayed library for "{mood}" + "{time}". Your unplayed games are mostly: {top 3 genres in unplayed list}. Want me to check your full library instead, or look up something new? Feature 3: Wishlist Sale Monitor API Call GET https://store.steampowered.com/wishlist/profiles/{STEAM_ID}/wishlistdata/ No API key needed — uses the Steam store API directly. Requires the user's wishlist to be public . Note: This endpoint may paginate. If the response contains exactly 50 items, make additional requests: GET https://store.steampowered.com/wishlist/profiles/{STEAM_ID}/wishlistdata/?p=1 GET https://store.steampowered.com/wishlist/profiles/{STEAM_ID}/wishlistdata/?p=2 Continue incrementing p until the response is empty or contains fewer than 50 items. Page 0 is the default. Response Fields Used Each entry is keyed by appid : { "730" : { "name" : "Counter-Strike 2" , "capsule" : "url-to-image" , "review_score" : 7 , "review_desc" : "Very Positive" , "reviews_total" : "7,456,123" , "reviews_percent" : 86 , "release_date" : "1694649600" , "release_string" : "Sep 27, 2023" , "priority" : 0 , "added" : 1680000000 , "background" : "url" , "rank" : 14 , "tags" : [ "FPS" , "Shooter" ] , "is_free_game" : false , "subs" : [ { "id" : 54029 , "discount_block" : "<div ...>-75%</div>" , "discount_pct" : 75 , "price" : "749" } ] } } Logic Rules Iterate over all wishlist entries For each entry, check subs array. A game is on sale if any sub has discount_pct > 0 The price field is the current (discounted) price in cents (e.g. 749 = $7.49 ). If price is a string, parse it as an integer first. Calculate original price: original_price = price / (1 - discount_pct / 100) Sort results by discount_pct descending (biggest discounts first) Response Format If sales found: 🏷️ Wishlist Sales — {count} game(s) on sale! {for each discounted game, sorted by discount_pct desc:} 🔥 {name} — {discount_pct}% OFF 💰 ${sale_price} (was ${original_price}) ⭐ {review_desc} ({reviews_percent}% positive) 🔗 https://store.steampowered.com/app/{appid} {end} 💡 Prices are current as of this check. Steam sales change without notice. If no sales: 🏷️ Wishlist Sales No games on your wishlist are currently discounted. 📋 You have {total_wishlist_count} games wishlisted. Top 3 by priority: 1. {name} — {review_desc} 2. {name} — {review_desc} 3. {name} — {review_desc} 💡 Major Steam sales happen in June (Summer Sale) and December (Winter Sale). If wishlist is empty or inaccessible: ⚠️ Couldn't access your wishlist. This usually means your wishlist is set to private. To fix: 1. Go to your Steam profile → Edit Profile → Privacy Settings 2. Set "Game details" to Public 3. Try again If it's already public, Steam's wishlist API may be temporarily down. Try again in a few minutes. Feature 4: Achievement Tracker Step 1: Get Player Achievements GET https://api.steampowered.com/ISteamUserStats/GetPlayerAchievements/v1/ Query parameters: Parameter Value key {STEAM_API_KEY} steamid {STEAM_ID} appid {appid} l english Response fields: { "playerstats" : { "steamID" : "76561198012345678" , "gameName" : "Hades" , "success" : true , "achievements" : [ { "apiname" : "AchUnlockAll" , "achieved" : 1 , "unlocktime" : 1695000000 } ] } } achieved : 1 = unlocked, 0 = locked unlocktime : Unix timestamp (0 if locked) Step 2: Get Achievement Schema (for human-readable names + descriptions) GET https://api.steampowered.com/ISteamUserStats/GetSchemaForGame/v2/ Query parameters: Parameter Value key {STEAM_API_KEY}