HOI4 AI Modding Skills

HOI4 AI Modding Skills

Build, review, debug, and maintain Hearts of Iron IV mods with AI-assisted, evidence-based development workflows.

HOI4 AI Modding Skills is a free, open-source toolkit consisting of three interconnected Agent Skills for Hearts of Iron IV mod development.

Designed for Codex, Claude Code, Cursor, Gemini CLI, and other compatible AI coding assistants, the suite helps both beginners and experienced modders turn ideas into working implementations, understand complex existing mods, diagnose failures, and maintain compatibility across game updates.

Rather than treating Paradox Script as a collection of isolated text files, the toolkit approaches mod development as a connected engineering process involving game logic, scopes, identifiers, AI behavior, localisation, graphics, state lifecycles, dependencies, and reproducible validation.

The problem

HOI4 modding is deceptively complex.

A single feature may depend on scripts, triggers, effects, sprites, localisation entries, AI rules, DLC availability, and other files scattered across a mod project.

An AI assistant can generate plausible-looking Paradox Script while overlooking incorrect scopes, missing identifiers, unsupported syntax, or dependencies that only become apparent during gameplay.

Existing mods introduce additional challenges: version migrations, conflicting overrides, performance bottlenecks, broken localisation, confusing error logs, and bugs that cannot be identified by checking syntax alone.

This toolkit provides structured workflows to make AI-assisted mod development more systematic, maintainable, and verifiable.

What you get

This package contains three complementary Agent Skills.

1. hoi4-content-builder — Build new mods and features

Turn natural-language descriptions into structured HOI4 implementations without requiring prior knowledge of PDX scripting.

Capabilities include:

• New countries, history, starting armies, and orders of battle.
• National focus trees, events, decisions, characters, and ideas.
• Military systems, equipment, doctrines, and Military Industrial Organizations.
• Special Projects, raids, operations, Balance of Power, diplomacy, and other advanced mechanics.
• AI strategies and gameplay behavior.
• Custom GUI/GFX, icons, animated textures, shaders, map presentation, and multimedia integration.
• Reusable templates, multi-file implementation kits, country scaffolding, and sprite registration helpers.
• Technical documentation, testing plans, and release preparation.

The Builder focuses on producing complete feature implementations, not just isolated script fragments.

2. hoi4-pdx-modding — PDX scripting and engineering

Provides the technical foundation for implementing, explaining, refactoring, and validating Hearts of Iron IV mod code.

Capabilities include:

• Paradox Script syntax, scopes, effects, triggers, variables, arrays, and event targets.
• Cross-file identifier tracing and dependency verification.
• Version-sensitive syntax checks against the target game installation.
• Localisation, encoding, GUI/GFX registration, and player-facing text.
• Mod structure, scripting architecture, and performance-conscious implementation.
• Compatibility analysis, dependency handling, and version migration guidance.
• Technical documentation and structured validation procedures.

The emphasis is on verifying unfamiliar or version-sensitive behavior against actual game resources rather than relying exclusively on an AI model's internal knowledge.

3. hoi4-review-debug — Mod Doctor and maintenance

Reviews and diagnoses existing HOI4 mods using source code, logs, project context, installed-game evidence, and optional authorized runtime tests.

Capabilities include:

• Whole-mod health checks and cross-file dependency audits.
• Error-log analysis, parser failures, and scope-related bug diagnosis.
• Crash investigation and evidence-based troubleshooting.
• Missing, duplicated, conflicting, or orphaned identifiers.
• Localisation, GUI, GFX, icons, and media consistency checks.
• Performance hotspots, periodic effects, AI behavior, and state lifecycle analysis.
• Compatibility reviews, vanilla overrides, and game-version migration.
• Gameplay balance, user experience, and maintainability reviews when requested.
• Prioritized findings supported by source references and reproducible evidence.

The review workflow distinguishes confirmed defects from potential risks, heuristic warnings, and intentional design decisions.

Reviewing a mod does not automatically authorize modifying its files.

How it works

Step 1 — Identify the task

Describe what you want in ordinary language.

You can ask the Agent to create a new feature, explain unfamiliar PDX code, diagnose a crash, migrate a mod, or review an existing project.

The appropriate Skill guides the workflow, with supporting references from the other Skills when needed.

Step 2 — Inspect the environment

The Agent examines the relevant mod files, installed HOI4 version, dependencies, DLC requirements, project conventions, and available documentation.

For existing features, it also examines player-facing localisation and the expected gameplay behavior before proposing changes.

Step 3 — Build or investigate

For new development, the Agent establishes an implementation plan and connects the required definitions, triggers, effects, assets, AI behavior, and localisation.

For maintenance or debugging, it traces relevant code paths, identifies possible failure mechanisms, and presents findings supported by available evidence.

Step 4 — Validate proportionally

The workflow selects appropriate checks based on the scope of the task.

Small changes do not automatically trigger expensive whole-mod audits. Larger changes may require broader checks, log analysis, compatibility testing, and regression review.

Static verification, runtime observations, and unresolved assumptions are reported separately.

Step 5 — Test and document

When suitable native computer-control tools are available, and the user has authorized testing, the Agent may follow a controlled HOI4 runtime-testing procedure.

Otherwise, it provides a manual testing handoff when appropriate.

Implementation changes are accompanied by relevant technical documentation and verification results.

Frameworks & tools

Game engine and scripting

• Hearts of Iron IV
• Paradox/PDX Script
• Clausewitz engine conventions
• HOI4 game and DLC resources, where available

Development and validation

• Git and repository-based workflows
• PowerShell validation and scaffolding scripts
• CWTools and HOI4 Mod Utilities as optional editor and preview aids
• Current installed-game documentation and vanilla/dependency implementations
• Logs, cross-file analysis, and targeted validation procedures

Optional Codex Plugin

The GitHub repository also provides a separate Codex Plugin containing the three Skills and five local, read-only MCP tools.

These optional tools support environment discovery, identifier tracing, changed-file validation, bounded log reading, and media metadata inspection.

The MCP helper runs locally. It does not launch HOI4, modify mod files, or provide automatic gameplay control.

The standalone Agensi Skills package does not automatically install the Codex Plugin or its MCP tools.

Why use this instead of generic AI prompting?

General-purpose AI assistants can help write HOI4 scripts, but their outputs may depend heavily on model memory, incomplete context, or outdated examples.

This toolkit adds a reusable engineering framework built around:

• Evidence-first development: Check uncertain syntax and behavior against current game resources.
• Cross-file completeness: Consider the full dependency chain instead of only the central script.
• Semantic consistency: Check whether actual implementation matches player-facing descriptions and intended behavior.
• Version awareness: Account for differences between HOI4 releases, DLCs, dependencies, and overrides.
• Structured diagnosis: Separate confirmed errors, likely causes, and unresolved questions.
• Resource-aware validation: Match the amount of testing to the task and available AI usage budget.
• Explicit authorization boundaries: Respect user approval before modifying files or performing potentially costly or intrusive tests.
• Maintainable implementation: Preserve existing project conventions, documentation, and unrelated work.

These workflows help reduce avoidable mistakes and improve traceability. They do not guarantee flawless code or eliminate the need for human judgment.

Use cases

Create a new HOI4 mod

Describe a fictional or historical scenario and develop a playable mod structure with countries, focus trees, events, decisions, AI behavior, and relevant assets.

Extend an existing mod

Add interconnected gameplay mechanics while preserving established identifiers, dependencies, visual behavior, and compatibility requirements.

Diagnose errors and crashes

Investigate parser failures, broken events, incorrect scopes, unresolved localisation, missing GFX references, and relevant error logs.

Review a large existing project

Use the Mod Doctor workflow to investigate cross-file consistency, version compatibility, lifecycle risks, performance hotspots, and maintainability issues.

Migrate to a newer HOI4 version

Examine changed vanilla behavior, deprecated or modified scripting conventions, overridden files, and compatibility requirements before applying targeted changes.

Develop advanced visual systems

Work on scripted GUI, animated textures, procedural shader effects, specialized map rendering, and related graphics integration with appropriate testing.

Prepare a mod release

Review changes, run relevant checks, update technical documentation, prepare test procedures, and organize versioned release packages.

Installation & requirements

Important: Install all three Skills together for the complete workflow.

The three Skills share documentation, references, and verification rules. Installing only one may leave required sibling resources unavailable.

After extraction, the three Skill directories must remain siblings in your AI agent's supported Skills location.

For example, in a Codex-compatible project:

• .agents/skills/hoi4-content-builder/SKILL.md
• .agents/skills/hoi4-pdx-modding/SKILL.md
• .agents/skills/hoi4-review-debug/SKILL.md

Preserve each directory's supporting references, workflows, scripts, and assets.

Skill discovery and execution capabilities vary by AI client. Consult the project's GitHub installation documentation for client-specific setup.

Some local helper scripts require Windows PowerShell, while the optional Codex MCP helper