name	wow-addon-structure
description	Verbose guide for WoW Retail AddOn structure, .toc metadata, loading order, SavedVariables, and C_AddOns metadata and load APIs. Use when planning addon folder layout, file order, or SavedVariables wiring.

WoW AddOn Structure (Retail)

Scope

Retail only, current as of Patch 12.0.0.
Focuses on folder layout, .toc metadata, loading order, and SavedVariables.
Avoid deprecated or removed APIs and call out restricted directives.

When to use this skill

Use this skill when you need to:

Design or review an AddOn folder layout.
Author or audit a .toc file.
Reason about file load order and login events.
Wire SavedVariables or troubleshoot persistence.
Query or load AddOns via C_AddOns APIs.

How to use this skill

Start with layout and naming rules in references/ADDON_STRUCTURE.md.
Build the .toc file using references/TOC_FORMAT.md.
Plan initialization order with references/LOADING_LIFECYCLE.md.
Wire persistence with references/SAVED_VARIABLES.md.
Use C_AddOns metadata APIs from references/C_ADDONS_API.md.
Cross-check patterns in Blizzard UI source from references/VIEWING_BLIZZARD_UI.md.

Reference files

references/ADDON_STRUCTURE.md - Folder layout rules, naming, and common patterns.
references/TOC_FORMAT.md - .toc syntax, directives, and file order rules.
references/LOADING_LIFECYCLE.md - Load order, events, and login timeline.
references/SAVED_VARIABLES.md - Persistence rules and file locations.
references/C_ADDONS_API.md - Key C_AddOns metadata and load APIs.
references/VIEWING_BLIZZARD_UI.md - How to inspect Blizzard UI source.

Key rules and reminders

The AddOn folder name and .toc filename must match.
The .toc file is required and defines file load order.
Files load top to bottom in the .toc list.
SavedVariables are available after ADDON_LOADED unless LoadSavedVariablesFirst is used.
Use LoadOnDemand and C_AddOns.LoadAddOn for heavy modules.
Some .toc directives are restricted to Blizzard AddOns and are not available to third-party AddOns.

Sources

WoW AddOn Structure (Retail)

Scope

Retail only, current as of Patch 12.0.0.

Focuses on folder layout, .toc metadata, loading order, and SavedVariables.

Avoid deprecated or removed APIs and call out restricted directives.

When to use this skill

Use this skill when you need to:

Design or review an AddOn folder layout.

Author or audit a .toc file.

Reason about file load order and login events.

Wire SavedVariables or troubleshoot persistence.

Query or load AddOns via C_AddOns APIs.

How to use this skill

Start with layout and naming rules in references/ADDON_STRUCTURE.md.

Build the .toc file using references/TOC_FORMAT.md.

Plan initialization order with references/LOADING_LIFECYCLE.md.

Wire persistence with references/SAVED_VARIABLES.md.

Use C_AddOns metadata APIs from references/C_ADDONS_API.md.

Cross-check patterns in Blizzard UI source from references/VIEWING_BLIZZARD_UI.md.

Reference files

references/ADDON_STRUCTURE.md - Folder layout rules, naming, and common patterns.

references/TOC_FORMAT.md - .toc syntax, directives, and file order rules.

references/LOADING_LIFECYCLE.md - Load order, events, and login timeline.

references/SAVED_VARIABLES.md - Persistence rules and file locations.

references/C_ADDONS_API.md - Key C_AddOns metadata and load APIs.

references/VIEWING_BLIZZARD_UI.md - How to inspect Blizzard UI source.

Key rules and reminders

The AddOn folder name and .toc filename must match.

The .toc file is required and defines file load order.

Files load top to bottom in the .toc list.

SavedVariables are available after ADDON_LOADED unless LoadSavedVariablesFirst is used.

Use LoadOnDemand and C_AddOns.LoadAddOn for heavy modules.

Some .toc directives are restricted to Blizzard AddOns and are not available to third-party AddOns.

Sources

wow-addon-structure