This skill should be used when the user asks to "migrate to V13", "upgrade to Foundry V13", "update module for V13", "fix V13 compatibility", "convert to ESM", "use DataModel", or mentions V13-specific patterns like hook signature changes, actor.system vs actor.data.data, or Application V2. Provides comprehensive Foundry VTT V13 development patterns and migration guidance.
Provides Foundry VTT V13 migration guidance and development patterns. Triggers when users request V13 upgrades, ESM conversion, DataModel implementation, or mention V13-specific changes like hook signatures and actor.system data access.
/plugin marketplace add ImproperSubset/hh-agentics/plugin install fvtt-dev@hh-agenticsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Domain: Foundry VTT Module/System Development Status: Production-Ready Last Updated: 2026-01-05
This guide covers V13-specific patterns and migration from earlier versions. For modules targeting V13, follow these guidelines.
require) to ESM (import/export)actor.data.data to actor.system)ALWAYS use foundry.abstract.DataModel for defining data structures instead of plain JavaScript objects. DataModels provide:
DataSchemaExample:
class MyModuleData extends foundry.abstract.DataModel {
static defineSchema() {
const fields = foundry.data.fields;
return {
name: new fields.StringField({ required: true, blank: false }),
value: new fields.NumberField({ initial: 0, min: 0 }),
enabled: new fields.BooleanField({ initial: true })
};
}
}
Foundry V13 uses ECMAScript Modules (ESM) exclusively. Your code must:
import and export statements (NO require())"esmodules" in your manifest (NOT "scripts").js extensions in import paths when importing relative filesExample manifest entry:
{
"esmodules": ["scripts/module.js"],
"scripts": []
}
ALWAYS use game.i18n.localize() or game.i18n.format() for user-facing text. Never hardcode English strings.
// BAD
ui.notifications.info("Item created successfully");
// GOOD
ui.notifications.info(game.i18n.localize("MYMODULE.Notifications.ItemCreated"));
// For dynamic values
const message = game.i18n.format("MYMODULE.Notifications.ItemCreatedWithName", {
name: itemName
});
Localization files go in lang/en.json:
{
"MYMODULE.Notifications.ItemCreated": "Item created successfully",
"MYMODULE.Notifications.ItemCreatedWithName": "Item {name} created successfully"
}
Many hooks in V13 have different argument signatures than V12. Always check the current API documentation.
Example: createToken Hook
// V12 (OLD - WRONG in V13)
Hooks.on("createToken", (scene, tokenData, options, userId) => { });
// V13 (CORRECT)
Hooks.on("createToken", (tokenDocument, options, userId) => { });
V13 distinguishes between Document classes (e.g., Actor, Item) and their data models:
actor.name, item.systemactor.system to access system-specific data defined in your DataModelactor.data.data (deprecated pattern from V10)// BAD (V10 pattern)
const hp = actor.data.data.attributes.hp.value;
// GOOD (V13 pattern)
const hp = actor.system.attributes.hp.value;
Active Effects in V13 use a cleaner structure:
document.effects (EffectCollection)await actor.createEmbeddedDocuments("ActiveEffect", [effectData])key (path to property) and mode (add, multiply, override, etc.)const effectData = {
name: game.i18n.localize("MYMODULE.Effects.Blessed"),
icon: "icons/magic/light/beam-rays-yellow.webp",
changes: [{
key: "system.attributes.ac.bonus",
mode: CONST.ACTIVE_EFFECT_MODES.ADD,
value: "2"
}],
duration: { rounds: 10 }
};
await actor.createEmbeddedDocuments("ActiveEffect", [effectData]);
V13 has reorganized canvas layers. Use the correct layer references:
canvas.tokens - TokenLayercanvas.tiles - TilesLayercanvas.lighting - LightingLayercanvas.grid - GridLayerDialog construction now prefers Application V2 patterns in some contexts, but classic Dialogs still work:
new Dialog({
title: game.i18n.localize("MYMODULE.Dialog.Title"),
content: `<p>${game.i18n.localize("MYMODULE.Dialog.Content")}</p>`,
buttons: {
yes: {
icon: '<i class="fas fa-check"></i>',
label: game.i18n.localize("MYMODULE.Dialog.Confirm"),
callback: () => { /* action */ }
},
no: {
icon: '<i class="fas fa-times"></i>',
label: game.i18n.localize("MYMODULE.Dialog.Cancel")
}
},
default: "yes"
}).render(true);
When defining DataModel schemas, use these field types from foundry.data.fields:
StringField - Text dataNumberField - Numeric values (integers or floats)BooleanField - True/false valuesObjectField - Nested objectsArrayField - Arrays of valuesSchemaField - Nested DataModel schemaHTMLField - Sanitized HTML contentFilePathField - File paths (images, sounds, etc.)ColorField - Color values (hex strings)AngleField - Angles in degreesAlphaField - Alpha transparency (0-1)game.user.isGM or document permission checksfromUuidSync() or fromUuid() - For reliable document referencesYour module.json or system.json must declare V13 compatibility:
{
"id": "my-module",
"title": "My Module",
"version": "1.0.0",
"compatibility": {
"minimum": "13",
"verified": "13",
"maximum": "13"
},
"esmodules": ["scripts/init.js"],
"languages": [
{
"lang": "en",
"name": "English",
"path": "lang/en.json"
}
]
}
console.log() liberally, or set up proper logging with CONFIG.debugCONFIG.debug.hooks = true to see all hook executionsRemember: When in doubt, check the official Foundry VTT V13 API documentation at https://foundryvtt.com/api/
"esmodules" (not "scripts").js extensionsdefineSchema()document.system (not data.data)game.i18n.localize()Last Updated: 2026-01-05 Status: Production-Ready Maintainer: ImproperSubset
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.