Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/jburlison/wowaddonapiagents/wow-api-unit-playernpx skills add JBurlison/WoWAddonAPIAgents --skill wow-api-unit-playergit clone --depth 1 https://github.com/JBurlison/WoWAddonAPIAgentsWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/jburlison/wowaddonapiagents/wow-api-unit-player)<a href="https://agentmods.dev/skills/jburlison/wowaddonapiagents/wow-api-unit-player"><img src="https://agentmods.dev/badge/skills/jburlison/wowaddonapiagents/wow-api-unit-player.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00000 | $0.08971 |
| Opus 5 | $0.00000 | $0.04485 |
| Sonnet 5 | $0.00000 | $0.01794 |
| Haiku 4.5 | $0.00000 | $0.00897 |
Grade A, and why
wow-api-unit-player scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 4d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 724 lines — stays where its author put it; the contents beside it link to each section on GitHub.
---
name: wow-api-unit-player
description: "Complete reference for WoW Retail Unit and Player APIs — UnitId tokens, GUIDs, health/power/stats, auras, roles, casting, threat, inspection, paper doll, death/resurrection, and player-specific functions. Use when querying unit identity, health, power, auras, stats, combat state, group membership, casting info, threat, or player character details."
---
# Unit & Player API (Retail — Patch 12.0.0)
Comprehensive reference for all Unit, Player, UnitAuras, UnitRole, PaperDollInfo, and PlayerInfo APIs. Covers unit identification (UnitId tokens, GUIDs), health, power, stats, auras, casting, threat, group membership, inspection, and player-specific character functions.
> **Source of truth:** https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#Unit
> **UnitId reference:** https://warcraft.wiki.gg/wiki/UnitId
> **GUID reference:** https://warcraft.wiki.gg/wiki/GUID
> **Current as of:** Patch 12.0.0 (Build 65655) — January 28, 2026
> **Scope:** Retail only. No deprecated or removed functions.
## Scope
This skill covers these API systems:
- **Unit** — Core unit query functions (`UnitName`, `UnitHealth`, `UnitClass`, etc.)
- **UnitAuras** — Aura/buff/debuff system (`C_UnitAuras`)
- **UnitRole** — Group role assignment and queries
- **PlayerInfo** — Player-specific info (`C_PlayerInfo`)
- **PaperDollInfo** — Equipment, stats, inspection (`C_PaperDollInfo`)
- **PlayerScript** — Global player functions (stats, combat ratings, PvP, death, movement)
- **DeathInfo / IncomingSummon** — Death, resurrection, summoning
- **CreatureInfo** — Creature data helpers
## When to Use This Skill
Use this skill when you need to:
- Query unit identity: name, class, race, level, faction, GUID
- Read or display health, power (mana/rage/energy), or stats
- Work with auras (buffs, debuffs, private auras)
- Check unit state: alive, dead, ghost, combat, AFK, stealthed, flying
- Determine group membership, roles, or raid position
- Inspect other players (item level, spec, PvP data)
- Get player character stats: crit, haste, mastery, armor, attack power
- Handle casting info (what a unit is casting/channeling)
- Query threat situation
- Work with UnitId tokens or GUIDs
## Reference Files
| Reference | Contents |
|-----------|----------|
| [UNIT-IDENTITY.md](references/UNIT-IDENTITY.md) | UnitId tokens, GUIDs, name/class/race/level/faction |
| [UNIT-HEALTH-POWER.md](references/UNIT-HEALTH-POWER.md) | Health, power, stats, armor, combat ratings |
| [UNIT-STATE.md](references/UNIT-STATE.md) | Combat, dead/ghost, casting, vehicle, movement, group state |
| [UNIT-AURAS.md](references/UNIT-AURAS.md) | C_UnitAuras — buffs, debuffs, private auras |
| [UNIT-THREAT-COMBAT.md](references/UNIT-THREAT-COMBAT.md) | Threat, targeting, selection, inspection |
| [PLAYER-FUNCTIONS.md](references/PLAYER-FUNCTIONS.md) | Player-specific: XP, money, PvP, death, resurrection, stats |
---
## UnitId Tokens — Quick Reference
A UnitId (unit token) identifies a unit by relationship to the player. Case insensitive.
### Base Tokens
| Token | Description |
|-------|-------------|
| `"player"` | The current player |
| `"target"` | The current player's target |
| `"focus"` | The player's focus target (set by `/focus`) |
| `"pet"` | The player's pet |
| `"vehicle"` | The player's vehicle |
| `"mouseover"` | Unit currently (or most recently) moused over |
| `"none"` | Valid token that always refers to no unit |
| `"npc"` | NPC the player is interacting with (merchant/quest/gossip frame open) |
| `"questnpc"` | Quest giver NPC being interacted with |
### Indexed Tokens
| Pattern | Range | Description |
|---------|-------|-------------|
| `"partyN"` | 1–4 | Nth party member (excluding player) |
| `"raidN"` | 1–40 | Nth raid member |
| `"partypetN"` | 1–4 | Pet of Nth party member |
| `"raidpetN"` | 1–40 | Pet of Nth raid member |
| `"bossN"` | 1–8 | Active boss in current encounter |
| `"arenaN"` | 1–5 | Opposing arena member |
| `"nameplateN"` | 1–40 | Nth nameplate (cannot be targeted) |
### Soft Targeting (Patch 10.0+)
| Token | Description |
|-------|-------------|
| `"softenemy"` | Current soft target that is hostile |
| `"softfriend"` | Current soft target that is friendly |
| `"softinteract"` | Current soft target that can be interacted with |
| `"anyenemy"` | Resolves to `"target"` or `"softenemy"` (target priority) |
| `"anyfriend"` | Resolves to `"target"` or `"softfriend"` (target priority) |
| `"anyinteract"` | Resolves to `"target"` or `"softinteract"` (target priority) |
### Target Chaining
Append `target` to any UnitId to refer to its target. Can be repeated:
- `"targettarget"` — your target's target
- `"raid7target"` — 7th raid member's target
- `"pettarget"` — your pet's target
- `"Cogwheel-target"` — named player's target (if in group)
> **Source:** https://warcraft.wiki.gg/wiki/UnitId
---
## GUID (Globally Unique Identifier) — Quick Reference
GUIDs uniquely identify everything the player can interact with. Returned by `UnitGUID(unit)`.
### GUID Formats
| Type | Format | Example |
|------|--------|---------|
| Player | `Player-[serverID]-[playerUID]` | `Player-970-0002FD64` |
| Creature | `Creature-0-[serverID]-[instanceID]-[zoneUID]-[npcID]-[spawnUID]` | `Creature-0-1465-0-2105-448-000043F59F` |
| Pet | `Pet-0-[serverID]-[instanceID]-[zoneUID]-[npcID]-[spawnUID]` | `Pet-0-4234-0-6610-165189-0202F859E9` |
| Vehicle | `Vehicle-0-[serverID]-[instanceID]-[zoneUID]-[npcID]-[spawnUID]` | Same format as Creature |
| GameObject | `GameObject-0-[serverID]-[instanceID]-[zoneUID]-[objectID]-[spawnUID]` | Same format as Creature |
| Item | `Item-[serverID]-0-[spawnUID]` | `Item-1598-0-4000000A369860E1` |
| Vignette | `Vignette-0-[serverID]-[instanceID]-[zoneUID]-[vignetteID]-[spawnUID]` | — |
| BattlePet | `BattlePet-0-[ID]` | `BattlePet-0-00000338F951` |
| Cast | `Cast-[type]-[serverID]-[instanceID]-[zoneUID]-[spellID]-[castUID]` | — |
### Extracting NPC ID from GUID
```lua
local npcID = select(6, strsplit("-", UnitGUID("target")))
print(tonumber(npcID)) -- e.g., 448 for Hogger
Key Rules
- Players keep their GUID forever (unless faction change/transfer)
- Creatures get a new GUID each spawn cycle
- Pets get a new GUID each time summoned
- GUIDs are recycled after server/instance restart
Core Unit Functions — Overview
Identity
| Function | Returns | Description |
|---|---|---|
UnitName(unit) |
unitName, unitServer |
Unit's name and realm |
UnitFullName(unit) |
unitName, unitServer |
Full name with server |
UnitNameUnmodified(unit) |
unitName, unitServer |
Name without modifications |
UnitNameFromGUID(guid) |
unitName, unitServer |
Name from GUID |
UnitGUID(unit) |
guid |
GUID string |
UnitTokenFromGUID(guid) |
unitToken |
UnitId from GUID |
UnitClass(unit) |
className, classFilename, classID |
Class info |
UnitClassBase(unit) |
classFilename, classID |
Non-localized class |
UnitClassFromGUID(guid) |
className, classFilename, classID |
Class from GUID |
UnitRace(unit) |
localizedRace, englishRace, raceID |
Race info |
UnitSex(unit) |
sex |
Gender (1=unknown, 2=male, 3=female) |
UnitLevel(unit) |
level |
Unit level |
UnitEffectiveLevel(unit) |
level |
Scaled level |
UnitFactionGroup(unit [, checkDisplayRace]) |
factionTag, localized |
Horde/Alliance |
UnitClassification(unit) |
class |
"normal", "elite", "worldboss", etc. |
UnitCreatureType(unit) |
name, id |
Beast, Humanoid, Undead, etc. |
UnitCreatureFamily(unit) |
name, id |
Creature family (e.g., Crab) |
UnitCreatureID(unit) |
creatureID |
NPC ID |
UnitPVPName(unit) |
name |
Name with title |
GetPlayerInfoByGUID(guid) |
class, engClass, race, engRace, sex, name, realm |
Info from GUID |
Health
| Function | Returns | Notes |
|---|---|---|
UnitHealth(unit [, usePredicted]) |
health |
Returns secret value in 12.0 — pass directly to widgets |
UnitHealthMax(unit) |
maxHealth |
Returns secret value in 12.0 |
UnitHealthMissing(unit [, usePredicted]) |
missing |
Health deficit |
UnitHealthPercent(unit [, usePredicted [, curve]]) |
percent |
Health percentage |
UnitPercentHealthFromGUID(guid) |
percent |
Health % from GUID |
UnitGetIncomingHeals(unit [, healer]) |
amount |
Predicted heals |
UnitGetTotalAbsorbs(unit) |
amount |
Damage absorb shield |
UnitGetTotalHealAbsorbs(unit) |
amount |
Healing absorb shield |
GetUnitHealthModifier(unit) |
modifier |
Health modifier |
GetUnitMaxHealthModifier(unit) |
modifier |
Max health modifier |
Power (Mana/Rage/Energy/etc.)
| Function | Returns | Notes |
|---|---|---|
UnitPower(unit [, powerType [, unmodified]]) |
power |
Current power |
UnitPowerMax(unit [, powerType [, unmodified]]) |
maxPower |
Maximum power |
UnitPowerMissing(unit [, powerType [, unmodified]]) |
missing |
Power deficit |
UnitPowerPercent(unit [, powerType [, ...]]) |
percent |
Power percentage |
UnitPartialPower(unit [, powerType [, unmodified]]) |
partialPower |
Fractional power |
UnitPowerType(unit [, index]) |
powerType, token, r, g, b |
e.g., 0=Mana, 1=Rage |
UnitPowerDisplayMod(powerType) |
mod |
Display modifier |
GetUnitPowerModifier(unit) |
modifier |
Power modifier |
Power Types (Enum.PowerType)
| Value | Token | Description |
|---|---|---|
| 0 | Mana | Mana |
| 1 | Rage | Rage |
| 2 | Focus | Focus (Hunter pets) |
| 3 | Energy | Energy (Rogues, Monks, etc.) |
| 4 | ComboPoints | Combo Points |
| 5 | Runes | Death Knight Runes |
| 6 | RunicPower | Runic Power |
| 7 | SoulShards | Warlock Soul Shards |
| 8 | LunarPower | Balance Druid |
| 9 | HolyPower | Paladin Holy Power |
| 11 | Maelstrom | Shaman Maelstrom |
| 12 | Chi | Monk Chi |
| 13 | Insanity | Shadow Priest |
| 16 | ArcaneCharges | Arcane Mage |
| 17 | Fury | Demon Hunter Fury |
| 18 | Pain | Vengeance DH (legacy) |
| 19 | Essence | Evoker Essence |
State Checks
| Function | Returns | Description |
|---|---|---|
UnitExists([unit]) |
bool |
Unit exists and can be targeted |
UnitIsVisible([unit]) |
bool |
Visible to client (not necessarily line of sight) |
UnitIsConnected(unit) |
bool |
Not offline |
UnitIsDead(unit) |
bool |
Dead |
UnitIsDeadOrGhost(unit) |
bool |
Dead or ghost form |
UnitIsGhost(unit) |
bool |
Ghost form |
UnitAffectingCombat(unit) |
bool |
In combat |
UnitIsAFK(unit) |
bool |
AFK (friendly only) |
UnitIsDND(unit) |
bool |
Do Not Disturb |
UnitIsPlayer([unit]) |
bool |
Is a player character |
UnitIsEnemy(unit, target) |
bool |
Units are hostile |
UnitIsFriend(unit, target) |
bool |
Units are friendly |
UnitCanAttack(unit, target) |
bool |
First can attack second |
UnitCanAssist(unit, target) |
bool |
First can assist second |
UnitCanCooperate(unit, target) |
bool |
Can cooperate |
UnitIsUnit(unit1, unit2) |
bool |
Same unit |
UnitIsPVP(unit) |
bool |
PvP flagged |
UnitIsCharmed([unit]) |
bool |
Charmed / mind controlled |
UnitIsFeignDeath(unit) |
bool |
Feigning death (group only) |
UnitIsTapDenied(unit) |
bool |
Tap denied (grey health bar) |
UnitIsTrivial(unit) |
bool |
Grey to player |
UnitIsBossMob(unit) |
bool |
Boss unit |
IsFalling([unit]) |
bool |
Currently falling |
IsFlying([unit]) |
bool |
On flying mount |
IsSwimming([unit]) |
bool |
Swimming |
IsStealthed() |
bool |
Player is stealthed |
PlayerIsInCombat() |
bool |
Player in combat |
Group Membership
| Function | Returns | Description |
|---|---|---|
UnitInParty([unit]) |
bool |
In your party |
UnitInRaid([unit]) |
index |
In your raid (returns index) |
UnitInAnyGroup([unit]) |
bool |
In any group |
UnitPlayerOrPetInParty([unit]) |
bool |
Player or pet in party |
UnitPlayerOrPetInRaid([unit]) |
bool |
Player or pet in raid |
UnitInRange(unit) |
inRange, checked |
Within 40yd (25yd Evoker) #grouponly |
UnitIsGroupLeader(unit [, cat]) |
bool |
Is group leader |
UnitIsGroupAssistant(unit) |
bool |
Is assist |
UnitGroupRolesAssigned([unit]) |
role |
"TANK", "HEALER", "DAMAGER", "NONE" |
UnitIsInMyGuild(unit) |
bool |
Same guild |
Casting Info
| Function | Returns | Description |
|---|---|---|
UnitCastingInfo(unit) |
name, displayName, textureID, startTimeMs, endTimeMs, isTradeskill, castID, notInterruptible, castingSpellID, castBarID |
Current cast info |
UnitChannelInfo(unit) |
name, displayName, textureID, startTimeMs, endTimeMs, isTradeskill, notInterruptible, spellID, isEmpowered, numEmpowerStages, castBarID |
Channel info |
UnitCastingDuration(unit) |
duration |
Cast duration |
UnitChannelDuration(unit) |
duration |
Channel duration |
UnitEmpoweredChannelDuration(unit [, includeHold]) |
duration |
Empower duration |
12.0.0 Change:
notInterruptibleinUnitCastingInfois now nilable. NewcastBarIDreturn added.
Threat
| Function | Returns | Description |
|---|---|---|
UnitThreatSituation(unit [, mob]) |
status |
0=low, 1=close, 2=unsafe, 3=tanking |
UnitDetailedThreatSituation(unit, mob) |
isTanking, status, scaledPct, rawPct, rawThreat |
Detailed threat |
UnitThreatPercentageOfLead(unit, mob) |
percent |
% of lead |
UnitThreatLeadSituation(unit, mob) |
status |
Lead situation |
C_UnitAuras — Aura System
The aura API provides buff/debuff data for units. Returns AuraData tables.
Key Functions
| Function | Returns | Description |
|---|---|---|
C_UnitAuras.GetAuraDataByIndex(unit, index [, filter]) |
aura |
Aura by index |
C_UnitAuras.GetAuraDataByAuraInstanceID(unit, auraInstanceID) |
aura |
Aura by instance ID |
C_UnitAuras.GetAuraDataBySlot(unit, slot) |
aura |
Aura by slot |
C_UnitAuras.GetAuraDataBySpellName(unit, spellName [, filter]) |
aura |
Aura by spell name |
C_UnitAuras.GetBuffDataByIndex(unit, index [, filter]) |
aura |
Buff specifically |
C_UnitAuras.GetDebuffDataByIndex(unit, index [, filter]) |
aura |
Debuff specifically |
C_UnitAuras.GetPlayerAuraBySpellID(spellID) |
aura |
Player aura by spell ID |
C_UnitAuras.GetAuraSlots(unit [, filter [, max [, token]]]) |
continuation, slots... |
Iterate aura slots |
C_UnitAuras.GetUnitAuraInstanceIDs(unit, filter [, max [, sort [, dir]]]) |
auraInstanceIDs |
All aura instance IDs |
C_UnitAuras.GetUnitAuras(unit, filter [, max [, sort [, dir]]]) |
auras |
All aura data |
C_UnitAuras.GetAuraDuration(unit, auraInstanceID) |
duration |
Remaining duration |
C_UnitAuras.GetAuraBaseDuration(unit, auraID [, spellID]) |
duration |
Base duration |
C_UnitAuras.DoesAuraHaveExpirationTime(unit, auraID) |
bool |
Has timer |
C_UnitAuras.IsAuraFilteredOutByInstanceID(unit, auraID, filter) |
bool |
Filtered by current filter |
C_UnitAuras.WantsAlteredForm(unit) |
bool |
Wants altered form |
Aura Filter Strings
Filters are space-separated strings passed to aura query functions:
| Filter | Description |
|---|---|
"HELPFUL" |
Buffs only |
"HARMFUL" |
Debuffs only |
"PLAYER" |
Only auras cast by the player |
"RAID" |
Only auras relevant to the raid |
"CANCELABLE" |
Only cancelable auras |
"NOT_CANCELABLE" |
Only non-cancelable auras |
"INCLUDE_NAME_PLATE_ONLY" |
Include nameplate-only auras |
"MAW" |
Maw-specific auras |
Combine with spaces: "HELPFUL PLAYER" = buffs cast by player.
AuraData Structure
Fields returned in an AuraData table:
| Field | Type | Description |
|---|---|---|
name |
string | Aura name |
icon |
number | Texture file ID |
applications |
number | Stack count |
dispelName |
string? | Dispel type: "Magic", "Curse", "Disease", "Poison" |
duration |
number | Total duration (0 = indefinite) |
expirationTime |
number | GetTime() when it expires |
isFromPlayerOrPlayerPet |
bool | Cast by player or player's pet |
isHarmful |
bool | Is a debuff |
isHelpful |
bool | Is a buff |
isNameplateOnly |
bool | Only shows on nameplates |
isRaid |
bool | Shows in raid frames |
isStealable |
bool | Can be spellstolen |
sourceUnit |
UnitId? | Caster |
spellId |
number | Spell ID |
points |
table | Aura effect values |
auraInstanceID |
number | Unique instance ID for this application |
timeMod |
number | Time modifier |
charges |
number | Number of charges |
isBossAura |
bool | Boss aura |
nameplateShowAll |
bool | Show all stacks on nameplate |
nameplateShowPersonal |
bool | Show personal on nameplate |
Private Auras
Private auras are auras where the spell data is hidden from addons. Used for encounter mechanics.
| Function | Description |
|---|---|
C_UnitAuras.AddPrivateAuraAnchor(args) |
Anchor a frame to a private aura's display position → anchorID |
C_UnitAuras.RemovePrivateAuraAnchor(anchorID) |
Remove private aura anchor |
C_UnitAuras.AddPrivateAuraAppliedSound(sound) |
Play sound when private aura applied → soundID |
C_UnitAuras.RemovePrivateAuraAppliedSound(soundID) |
Remove private aura sound |
C_UnitAuras.AuraIsPrivate(spellID) |
Check if spell is private |
C_UnitAuras.AuraIsBigDefensive(spellID) |
Check if big defensive CD |
C_UnitAuras.SetPrivateWarningTextAnchor(parent [, anchor]) |
Set warning text anchor |
C_UnitAuras.TriggerPrivateAuraShowDispelType(show) |
Toggle dispel type display |
Aura Iteration Pattern
-- Modern pattern: iterate by aura instance IDs
local function GetAllAuras(unit, filter)
local auras = {}
local ids = C_UnitAuras.GetUnitAuraInstanceIDs(unit, filter)
for _, id in ipairs(ids) do
local aura = C_UnitAuras.GetAuraDataByAuraInstanceID(unit, id)
if aura then
table.insert(auras, aura)
end
end
return auras
end
What ships with it
6 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 4d ago First seen · 724 lines · 0 tokens per session scan A e04ccbd1b945
wow-api-unit-player is a skill published in the GitHub repository JBurlison/WoWAddonAPIAgents (43 stars, last pushed 6mo ago), licensed MIT. It costs nothing until one of its globs matches a file; then it loads 8,971 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
gameobject-component-destroy
Destroy one or more Components from a target GameObject. Missing (null) components are skipped — they cannot be destroyed. Use 'gameobject-find' and 'gameobject-component-get' to identify the components first.
assets-prefab-save
Save the currently opened prefab edit stage back to its prefab asset without exiting the stage. Pair with 'assets-prefab-open' to enter the edit mode first.
mobile-games
Mobile game development principles. Touch input, battery, performance, app stores.
influence-psychology
Apply the seven principles of ethical persuasion (reciprocity, commitment, social proof, authority, liking, scarcity, unity) to product design, copy, and sales. Use when the user mentions "social proof", "persuasive copy", "why users dont convert", "ethical persuasion", "reciprocity", "scarcity tactics", "commitment…
unity-addressables
Manage Addressables groups, entries, profiles and content builds (com.unity.addressables, reflection-based).
unity-manual-component
Manually add, configure, reorder, and copy components on GameObjects using Unity Editor UI. For one-off Inspector workflows that do not need REST automation.