steam-gaming-companion

What this skill does

# 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)

1. Go to https://steamcommunity.com/dev/apikey
2. Sign in with your Steam account
3. Enter any domain name (e.g. `localhost`) — it doesn't matter for personal use
4. Click **Register** and copy the key
5. 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.

1. Go to https://steamid.io
2. Paste your Steam profile URL (e.g. `https://steamcommunity.com/id/yourname`)
3. Copy the **steamID64** value (looks like `76561198012345678`)
4. 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.

1. Go to https://dev.twitch.tv/console/apps and log in with your Twitch account (create one if needed)
2. Click **Register Your Application**
3. Name: anything (e.g. `steam-companion`), OAuth Redirect: `http://localhost`, Category: **Application Integration**
4. Click **Manage** on your new app, copy the **Client ID**
5. Generate a **Client Secret** and copy it
6. 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'
   ```
7. Copy the `access_token` from the response
8. 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

```json
{
  "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

1. 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)

2. Filter the user's library to games with `playtime_forever < 60` (unplayed) OR `60 <= playtime_forever < 300` (abandoned — gave it a short try).

3. 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`

4. 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 |

5. 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. |

6. 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