HOI4 Modding Agent Skill
Use this skill when working on Hearts of Iron IV mods.
Operating Model
Treat HOI4 mods as Paradox data-script projects, not normal software projects.
Prioritize:
- small loadable edits
- existing project conventions
- valid folder structure
- unique IDs
- correct event namespaces
- correct scopes
- localization for all visible player-facing content
error.log-driven debugging
- compatibility with the current mod structure
Avoid:
- large speculative rewrites
- inventing syntax when a nearby project or vanilla-style pattern exists
- editing vanilla installation files directly
- copying proprietary game files or assets into public repositories
- adding GFX references without checking whether sprites/files exist
- adding visible UI content without localization keys
First Actions
Before editing:
- Inspect the active mod root.
- Identify the descriptor file and mod folder.
- Identify relevant country tags, file prefixes, event namespaces, idea prefixes, and localization prefixes.
- Search nearby files for existing conventions.
- Determine whether the requested change affects focus trees, events, decisions, ideas, history, localization, GFX, scripted effects, scripted triggers, map/state data, or descriptor files.
- If debugging, inspect
error.log before guessing from symptoms.
Reference Loading
Read the relevant reference files only when needed:
references/01-folder-structure.md for mod layout and descriptor issues.
references/02-paradox-script.md for Paradox script syntax, braces, scopes, triggers, and effects.
references/03-focus-trees.md for national focus trees.
references/04-events.md for event namespaces, event IDs, options, and event firing.
references/05-decisions.md for decision categories, visibility, availability, costs, and effects.
references/06-ideas-and-modifiers.md for ideas, national spirits, modifiers, and add_ideas.
references/07-countries-history-states.md for country setup, history files, states, and related references.
references/08-localization.md for localization files, keys, formatting, and visible text.
references/09-gfx-interface-icons.md for sprites, focus icons, .gfx, .dds, .tga, and interface references.
references/10-scripted-effects-triggers.md for reusable scripted logic and expected scopes.
references/11-debugging-error-log.md for debugging workflows.
references/13-common-failure-modes.md for known HOI4 modding mistakes.
Examples
Use examples/ for small original ABC placeholder snippets and examples/broken-cases/ for debugging patterns. Treat examples as educational starting points, not files to paste blindly into every mod.
Editing Checklist
Before finishing, verify:
- IDs are unique in the affected files.
- Event IDs match declared namespaces.
- Visible focus, event, decision, idea, and GUI text has localization.
- Localization keys match script references.
- Braces are balanced.
- Effects and triggers are used in valid scopes.
- Focus prerequisites reference existing focuses.
- Event calls reference existing events.
- Idea additions reference existing ideas.
- GFX references point to existing sprites/files or clearly marked placeholders.
- The change does not silently overwrite vanilla files unless intended.
- The change avoids bundling proprietary game assets.
- Do not claim in-game validation unless HOI4 was actually launched and tested.
Debugging Workflow
When a mod does not load or content does not appear:
- Check whether the mod is enabled in the active playset.
- Check descriptor and path issues.
- Read
error.log.
- Fix parse and syntax errors first.
- Fix missing or invalid scope errors.
- Fix missing localization.
- Fix missing sprite or GFX references.
- If HOI4 can be launched, test the smallest affected feature in-game. Otherwise, report this as a manual test step for the user.
- Summarize remaining risks.
If error.log is unavailable, ask the user for the relevant excerpt or explain what to inspect manually.
Response Format
When done, report:
- files changed
- IDs added or modified
- localization keys added
- what to test in HOI4
- likely risks
- whether validation was static-only or actually tested in-game
1---2name: hoi4-modding3description: Creates, edits, reviews, and debugs Hearts of Iron IV mods. Use for HOI4 focus trees, events, decisions, ideas, countries, states, history files, localization, GFX/interface references, scripted effects/triggers, descriptors, mod folder structure, and error.log issues.4license: MIT5metadata:6 source: https://skillmd.com/skills/postigodev/hoi4-modding7 domain: hearts-of-iron-iv-modding8 compatibility:9 - codex10 - claude11 - cursor12 - cline13 - agents-md14---1516# HOI4 Modding Agent Skill1718Use this skill when working on Hearts of Iron IV mods.1920## Operating Model2122Treat HOI4 mods as Paradox data-script projects, not normal software projects.2324Prioritize:2526- small loadable edits27- existing project conventions28- valid folder structure29- unique IDs30- correct event namespaces31- correct scopes32- localization for all visible player-facing content33- `error.log`-driven debugging34- compatibility with the current mod structure3536Avoid:3738- large speculative rewrites39- inventing syntax when a nearby project or vanilla-style pattern exists40- editing vanilla installation files directly41- copying proprietary game files or assets into public repositories42- adding GFX references without checking whether sprites/files exist43- adding visible UI content without localization keys4445## First Actions4647Before editing:48491. Inspect the active mod root.502. Identify the descriptor file and mod folder.513. Identify relevant country tags, file prefixes, event namespaces, idea prefixes, and localization prefixes.524. Search nearby files for existing conventions.535. Determine whether the requested change affects focus trees, events, decisions, ideas, history, localization, GFX, scripted effects, scripted triggers, map/state data, or descriptor files.546. If debugging, inspect `error.log` before guessing from symptoms.5556## Reference Loading5758Read the relevant reference files only when needed:5960- `references/01-folder-structure.md` for mod layout and descriptor issues.61- `references/02-paradox-script.md` for Paradox script syntax, braces, scopes, triggers, and effects.62- `references/03-focus-trees.md` for national focus trees.63- `references/04-events.md` for event namespaces, event IDs, options, and event firing.64- `references/05-decisions.md` for decision categories, visibility, availability, costs, and effects.65- `references/06-ideas-and-modifiers.md` for ideas, national spirits, modifiers, and `add_ideas`.66- `references/07-countries-history-states.md` for country setup, history files, states, and related references.67- `references/08-localization.md` for localization files, keys, formatting, and visible text.68- `references/09-gfx-interface-icons.md` for sprites, focus icons, `.gfx`, `.dds`, `.tga`, and interface references.69- `references/10-scripted-effects-triggers.md` for reusable scripted logic and expected scopes.70- `references/11-debugging-error-log.md` for debugging workflows.71- `references/13-common-failure-modes.md` for known HOI4 modding mistakes.7273## Examples7475Use `examples/` for small original ABC placeholder snippets and `examples/broken-cases/` for debugging patterns. Treat examples as educational starting points, not files to paste blindly into every mod.7677## Editing Checklist7879Before finishing, verify:8081- IDs are unique in the affected files.82- Event IDs match declared namespaces.83- Visible focus, event, decision, idea, and GUI text has localization.84- Localization keys match script references.85- Braces are balanced.86- Effects and triggers are used in valid scopes.87- Focus prerequisites reference existing focuses.88- Event calls reference existing events.89- Idea additions reference existing ideas.90- GFX references point to existing sprites/files or clearly marked placeholders.91- The change does not silently overwrite vanilla files unless intended.92- The change avoids bundling proprietary game assets.93- Do not claim in-game validation unless HOI4 was actually launched and tested.9495## Debugging Workflow9697When a mod does not load or content does not appear:98991. Check whether the mod is enabled in the active playset.1002. Check descriptor and path issues.1013. Read `error.log`.1024. Fix parse and syntax errors first.1035. Fix missing or invalid scope errors.1046. Fix missing localization.1057. Fix missing sprite or GFX references.1068. If HOI4 can be launched, test the smallest affected feature in-game. Otherwise, report this as a manual test step for the user.1079. Summarize remaining risks.108109If `error.log` is unavailable, ask the user for the relevant excerpt or explain what to inspect manually.110111## Response Format112113When done, report:114115- files changed116- IDs added or modified117- localization keys added118- what to test in HOI4119- likely risks120- whether validation was static-only or actually tested in-game