From 0ff1d2211a6a300c99b584613de06228f4bcc686 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Tue, 17 Feb 2026 10:38:11 -0600 Subject: [PATCH] Add project-local agent template and steam-game-setup skill Co-Authored-By: Claude Opus 4.6 --- .claude/agents/sample-sub-agent-template.md | 50 +++ .claude/skills/steam-game-setup/SKILL.md | 334 ++++++++++++++++++++ 2 files changed, 384 insertions(+) create mode 100644 .claude/agents/sample-sub-agent-template.md create mode 100644 .claude/skills/steam-game-setup/SKILL.md diff --git a/.claude/agents/sample-sub-agent-template.md b/.claude/agents/sample-sub-agent-template.md new file mode 100644 index 0000000..1f54da1 --- /dev/null +++ b/.claude/agents/sample-sub-agent-template.md @@ -0,0 +1,50 @@ +--- +name: sample-sub-agent-template +description: qqq What this agent does. Use proactively when qqq trigger conditions. +tools: Task, TaskOutput, Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, KillShell, AskUserQuestion, Skill, EnterPlanMode, ExitPlanMode +disallowedTools: Write, Edit +model: opus +permissionMode: default +skills: + - skill-name-1 + - skill-name-2 +hooks: + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "echo 'pre-hook'" + once: true + PostToolUse: + - matcher: "Edit|Write" + hooks: + - type: command + command: "echo 'post-hook'" + Stop: + - hooks: + - type: command + command: "echo 'stop-hook'" +color: cyan +--- + +# qqq Agent Title + +## Purpose + +You are qqq purpose definition. + +## Instructions + +qqq + +## Workflow + +When invoked, follow these steps: + +1. qqq +2. qqq +3. qqq + +## Report + +qqq diff --git a/.claude/skills/steam-game-setup/SKILL.md b/.claude/skills/steam-game-setup/SKILL.md new file mode 100644 index 0000000..c7e224b --- /dev/null +++ b/.claude/skills/steam-game-setup/SKILL.md @@ -0,0 +1,334 @@ +--- +name: steam-game-setup +description: Configure Steam games via SteamTinkerLaunch (STL) profiles or Steam launch arguments. Use when setting up a new game, fixing game issues, optimizing performance, or configuring Proton/DXVK/VKD3D settings. Handles modern DX12/RT games and retro DX9 titles. +allowed-tools: Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch, AskUserQuestion +--- + +# Steam Game Setup Skill + +Configure Steam games for optimal performance on Linux using SteamTinkerLaunch. + +## System Hardware + +- **CPU**: AMD Ryzen 7 7800X3D (8C/16T) +- **GPU**: NVIDIA GeForce RTX 4080 SUPER (16GB VRAM) +- **Display (primary)**: 2560x1440 @ 120Hz OLED with HDR +- **Display (secondary)**: 2560x1440 @ 60Hz (no HDR) + +## Configuration File Locations + +| File | Purpose | +|------|---------| +| `~/.config/steamtinkerlaunch/global.conf` | Global settings | +| `~/.config/steamtinkerlaunch/default_template.conf` | Template for new games | +| `~/.config/steamtinkerlaunch/gamecfgs/id/{APPID}.conf` | Per-game config | +| `~/.config/steamtinkerlaunch/gamecfgs/customvars/{APPID}.conf` | Per-game environment vars | + +## Workflow + +**Tools by step:** + +- **Research**: WebFetch (ProtonDB, PCGamingWiki), Grep/Glob (knowledge base) +- **Configuration**: Read (templates/existing configs), Write (new configs) +- **Verification**: Bash (file checks), Read (logs) +- **Clarification**: AskUserQuestion (user preferences) + +### Step 1: Get Game Info + +Ask for **game name**. Note any specific issues (won't launch, crashes, poor performance). + +### Step 2: Research Game + +Gather all required data before configuration: + +**Data points to collect:** + +| Data | Primary Source | Fallback | +|------|----------------|----------| +| Steam App ID | Steam store URL, SteamDB | WebSearch | +| Graphics API | PCGamingWiki "API" section | ProtonDB comments | +| RT/DLSS/HDR | PCGamingWiki "Features" | In-game settings | +| Linux issues | ProtonDB reports | - | +| Existing config | `/gaming/games/` | Create new | + +**Web research workflow:** + +1. **Find App ID**: Extract from Steam store URL or search SteamDB +2. **ProtonDB** (`https://www.protondb.com/app/{APPID}`): + - Rating (Platinum/Gold/Silver/Bronze/Borked) + - Top 3 reported issues from recent reviews + - Recommended Proton version if mentioned +3. **PCGamingWiki** (`https://www.pcgamingwiki.com/wiki/{Game_Name}`): + - Exact graphics API (look for "API" row in specs table) + - Ray tracing support and type + - Known Linux/Proton issues +4. **Knowledge base**: `Glob: /gaming/games/*{game-name}*.md` + +**Anti-cheat note:** If ProtonDB mentions EAC/BattlEye issues, check [areweanticheatyet.com](https://areweanticheatyet.com/) - some games require developer opt-in for Linux support. + +### Step 3: Present Findings + +```text +## {Game Name} - Feature Analysis + +**Steam App ID**: {APPID} +**Graphics API**: {API} + +| Feature | Supported | Notes | +|---------|-----------|-------| +| Ray Tracing | Yes/No | {type} | +| DLSS | Yes/No | | +| HDR | Yes/No | | + +**ProtonDB Rating**: {rating} +**Known Issues**: {summary} +``` + +Ask: "I'll enable all supported features. Any you want to skip?" + +### Step 4: Determine Configuration + +Use this decision tree: + +```text +Graphics API? +├── DX12 + Ray Tracing → See "DX12 + RT Settings" below +├── DX12 (no RT) → Standard DX12, enable DLSS if supported +├── UE5 with Lumen → See "UE5 Lumen Configuration" below +├── DX11 / Vulkan → See "DX11/Vulkan Settings" below +└── DX9 (pre-2010) → See "Retro Game Settings" below + +HDR supported? +├── Yes → See "HDR Configuration" below +└── No → Skip HDR settings +``` + +### Step 5: Create Configuration + +Create per-game config with header: + +```bash +## Game: {Game Name} +## AppID: {APPID} +## Engine: {Engine} ({Graphics API}) +## Features: {RT/DLSS/HDR status} +## Created: {YYYY-MM-DD} +``` + +### Step 6: Verify Configuration + +1. **Confirm config exists:** + + ```bash + ls ~/.config/steamtinkerlaunch/gamecfgs/id/{APPID}.conf + ``` + +2. **Test launch** - Watch for STL loading message in terminal + +3. **MangoHud verification** (once in-game): + - `API: VKD3D` = DX12 mode active (VKD3D-Proton translating) + - `API: VK` = DX11/Vulkan mode (DXVK translating) + - GPU name visible = NVAPI working + +4. **If issues**: See troubleshooting in `/gaming/tools/steamtinkerlaunch.md` + +### Step 7: Provide Summary + +After configuration: + +1. **Summary** - What was configured and why +2. **Expected behavior** - What the user should see +3. **Fallback options** - Reference relevant troubleshooting docs if issues occur + +--- + +## Settings Reference + +### Default Template Settings + +These are safe for ALL games in `default_template.conf`: + +```bash +# Always enabled - safe for all games +PROTON_ENABLE_NVAPI="1" # Required for GPU detection +PROTON_HIDE_NVIDIA_GPU="0" # MUST be 0 - do NOT hide GPU +DXVK_ASYNC="1" # Reduce shader compilation stuttering +USEGAMEMODERUN="1" # Enable GameMode +USEMANGOHUD="1" # Performance monitoring + +# UI preferences +WAITEDITOR="0" # Skip STL popup - edit configs via Claude Code + +# DISABLED by default - enable per-game only! +USEDLSS="0" # Enable per-game for DLSS titles +USERAYTRACING="0" # Enable per-game for DX12+RT ONLY +STL_VKD3D_CONFIG="none" # Set to "dxr" per-game for DX12+RT ONLY +``` + +### Per-Game Settings by Graphics API + +| Game Type | USERAYTRACING | VKD3D_CONFIG | HDR Via | Examples | +|-----------|---------------|--------------|---------|----------| +| DX12 + RT | 1 | "dxr" | PROTON_ENABLE_HDR | Satisfactory, Cyberpunk | +| DX12 (no RT) | 0 | "none" | PROTON_ENABLE_HDR | Some UE5 games | +| DX11 | 0 | "none" | DXVK_HDR | BG3, most games | +| DX9 (old) | 0 | "none" | N/A | CoD series | + +**Critical notes:** + +- `VKD3D_CONFIG="dxr"` is **required** for DX12 RT detection - without it, games won't see ray tracing +- `USERAYTRACING=1` on DX11/Vulkan causes launch failures - only enable for DX12+RT games + +--- + +## Custom Variables + +For environment variables not built into STL, create customvars files. + +**Location**: `~/.config/steamtinkerlaunch/gamecfgs/customvars/{APPID}.conf` + +STL automatically loads these based on AppID. + +### Template + +```bash +# Location: ~/.config/steamtinkerlaunch/gamecfgs/customvars/{APPID}.conf +# Purpose: {Game Name} - {brief description} +# Created: {YYYY-MM-DD} + +# Force NVIDIA GPU selection (useful for multi-GPU or iGPU systems) +DXVK_FILTER_DEVICE_NAME="NVIDIA" +VKD3D_FILTER_DEVICE_NAME="NVIDIA" + +# VKD3D shader cache (DX12 games - reduces compilation stutters) +VKD3D_SHADER_CACHE="1" +VKD3D_SHADER_CACHE_PATH="/home/cal/.cache/vkd3d-proton" + +# HDR settings (see HDR Configuration section) +PROTON_ENABLE_HDR="1" +ENABLE_HDR_WSI="1" +``` + +--- + +## HDR Configuration + +HDR works well in most games. Enable it by default for supported titles. + +### Setup (One-Time) + +1. **Install vk-hdr-layer** (required for NVIDIA): + + ```bash + paru -S vk-hdr-layer-kwin6-git + ``` + +2. **Enable KDE HDR**: System Settings → Display → Enable HDR +3. **Calibrate peak brightness** to match your monitor's actual spec + +### Enable HDR + +Add to `~/.config/steamtinkerlaunch/gamecfgs/customvars/{APPID}.conf`: + +**DX12 games:** + +```bash +PROTON_ENABLE_HDR="1" +ENABLE_HDR_WSI="1" +``` + +**DX11 games** (add DXVK_HDR): + +```bash +PROTON_ENABLE_HDR="1" +ENABLE_HDR_WSI="1" +DXVK_HDR="1" +``` + +### Troubleshooting HDR + +| Issue | Solution | +|-------|----------| +| HDR option missing | Install vk-hdr-layer-kwin6-git, add ENABLE_HDR_WSI | +| Still missing | Add PROTON_ENABLE_WAYLAND="1" (but see stuttering note) | +| HDR too dark | Lower KDE peak brightness to match monitor spec | +| HDR washed out | Raise KDE SDR brightness | +| Severe stuttering with HDR | Disable PROTON_ENABLE_WAYLAND (rare, affects PoE2) | + +--- + +## UE5 Lumen Configuration + +For UE5 games using Lumen GI without an in-game RT toggle, hardware ray tracing can be enabled via Engine.ini. This improves quality on RTX 40/50 series. + +**Full guide:** `/gaming/tools/ue5-lumen-hardware-raytracing.md` + +--- + +## Retro Gaming Settings (Pre-2010 Games) + +For old DirectX 9 games: + +### Steam Launch Options + +```bash +taskset -c 0-3 %command% +``` + +### Environment Variables (customvars) + +```bash +WINE_CPU_TOPOLOGY="4:2" # Tell Wine: 4 cores, 2 per socket +PULSE_LATENCY_MSEC="60" # Audio latency (increase if crackling) +DXVK_FRAME_RATE="120" # Cap FPS (old games have timing issues) +PROTON_NO_ESYNC="1" # Disable esync (fixes some hangs) +``` + +### CPU Affinity by Game Era + +| Game Era | Cores | taskset Args | WINE_CPU_TOPOLOGY | +|----------|-------|--------------|-------------------| +| 2000-2005 | 2 | `-c 0-1` | `2:1` | +| 2005-2010 | 4 | `-c 0-3` | `4:2` | +| 2010-2015 | 6 | `-c 0-5` | `6:3` | + +### WineD3D Fallback (if DXVK causes issues) + +```bash +PROTON_USE_WINED3D="1" # Use OpenGL instead of Vulkan +``` + +--- + +## Proton Settings Reference + +### Version Selection + +```bash +USEPROTON="GE-Proton10-26" # Pin to specific GE-Proton version +USEPROTON="Proton Experimental" # Use Valve's bleeding edge +``` + +### Sync Mechanisms + +```bash +PROTON_NO_ESYNC="0" # Keep esync enabled (default, good) +PROTON_NO_FSYNC="0" # Keep fsync enabled (default, good) +PROTON_NO_ESYNC="1" # Disable esync (try for old games) +``` + +### Memory and Compatibility + +```bash +PROTON_FORCE_LARGE_ADDRESS_AWARE="1" # Enable 4GB+ for 32-bit games +PROTON_NO_WRITE_WATCH="1" # Helps with some anti-cheat +``` + +--- + +## External Resources + +- [SteamTinkerLaunch Wiki](https://github.com/sonic2kk/steamtinkerlaunch/wiki) +- [VKD3D-Proton Environment Variables](https://github.com/HansKristian-Work/vkd3d-proton#environment-variables) +- [DXVK Configuration](https://github.com/doitsujin/dxvk#configuration) +- [ProtonDB](https://www.protondb.com/) \ No newline at end of file