WarcraftLogs Skill

How It Works

1. Figure out what the user is asking about
2. Pick a query template from references/queries.md or construct a custom query using references/schema.md
3. Execute via the bundled helper script: <skill-path>/scripts/wcl.sh '<GRAPHQL_QUERY>'
   • Optional second argument for variables: <skill-path>/scripts/wcl.sh '<QUERY>' '{"name": "value"}'
4. Interpret the results and present them clearly

The script handles OAuth authentication automatically (including retry on expired tokens). Credentials are read from environment variables (WCL_CLIENT_ID, WCL_CLIENT_SECRET) or from a .env file at ${CLAUDE_SKILL_DIR}/.env.

Identifying What to Query

User gives a WarcraftLogs URL

Extract the report code from the URL: https://www.warcraftlogs.com/reports/ABC123 → code is ABC123. Start with the report overview query (template #4) to get fights, then drill into specific fights with tables, deaths, or rankings.

User asks about a character

You need: character name, server slug (lowercase, hyphenated), and region (us, eu, kr, tw, cn). If the user doesn't specify server/region, ask them. Common examples: "illidan"/"us", "tarren-mill"/"eu", "ragnaros"/"eu".

User asks about a guild

Same as character — need guild name, server slug, region.

User asks a meta question ("what's the best spec")

This requires aggregating data. WarcraftLogs doesn't have a direct "best spec" API endpoint. Instead:

• For raid: look at character zone rankings across multiple well-known players, or reference what you know about the current meta and use specific character lookups to validate.
• For M+: look at zone rankings with metric: playerscore for high-performing characters.
• You can also suggest the user check the Archon tier lists on warcraftlogs.com, which aggregate this data at scale.

Reading the Results

Zone Rankings (zoneRankings)

Returns JSON with per-boss data. Key fields in the response:

• bestAmount — highest DPS/HPS value
• medianPerformance — median percentile across kills
• rankPercent — best percentile
• allStars — overall ranking across all bosses
  • points, rank, regionRank, serverRank, possiblePoints

Present percentiles with color context:

• 99-100: gold parse (exceptional)
• 95-98: pink parse (excellent)
• 75-94: orange parse (great)
• 50-74: purple parse (good)
• 25-49: blue parse (average)
• 0-24: gray parse (below average)

Encounter Rankings (encounterRankings)

Returns JSON with individual kill details:

• ranks[] — each kill with amount (DPS/HPS), duration, startTime, report { code, fightID }, bracketData
• bestAmount, medianPerformance, averagePerformance
• totalKills

Report Tables

Returns JSON with entries[] or compositions[]. Each entry has:

• name, id, total, activeTime, activeTimeReduced
• For damage: abilities[] with per-ability breakdowns
• For deaths: deathEvents[] with killing blow info

Guild Zone Rankings (zoneRanking)

Each sub-field (progress, speed, completeRaidSpeed) contains:

• worldRank { number percentile color } — global rank
• regionRank { number } — region rank
• serverRank { number } — server rank

Query Efficiency

The API has a 3600 points/hour rate limit. Be mindful:

• Combine related data into single queries using GraphQL's structure
• Use aliases to compare multiple characters in one request (template #15)
• Fetch report overview first, then drill into specific fights rather than loading everything
• Check rate limit (template #14) if you're doing many queries
• Cache the token (the script already does this)

When doing a multi-step analysis (like "analyze this log"), plan your queries:

1. First: report overview + master data (get fights and player IDs)
2. Then: specific fight tables/rankings based on what's interesting
3. Only fetch events if you need detailed timeline data (most expensive)

Presenting Results

• Format numbers: DPS as X.XXk or X.XXM, durations as Xm Xs
• Show percentiles prominently — they're what players care about most
• Use tables for multi-boss comparisons
• When comparing characters, show side-by-side
• Timestamps from the API are Unix milliseconds — convert to readable dates
• For report analysis, summarize before diving into details: "This was a 3-hour raid session with 8/8 Normal kills and 5/8 Heroic, wiping 4 times on Sprocketmonger"

Reference Files

• Read references/queries.md for ready-to-use query templates (covers ~80% of questions)
• Read references/schema.md for the full API schema when you need to construct custom queries
• The schema reference includes current zone IDs, encounter IDs, difficulty values, metric names, and enum values

Handling Errors

• null character/guild result: name or server is wrong. Ask the user to double-check.
• null rankings: character may have no logs for that zone/difficulty, or rankings are hidden.
• Token error: credentials may be missing. Check that .env file exists at ${CLAUDE_SKILL_DIR}/.env.
• Rate limit exceeded: tell the user to wait (check pointsResetIn from rate limit query).
• Archived report: older reports may require a subscription for event/table data.