An LLM-first instruction set for developing, debugging, and maintaining Factorio 2.0 / Space Age mods with zero-assumption rigor, compatibility-first design, and research-driven development.
Drop these files into any AI coding assistant that supports custom instructions or agent skills — including Cursor, Windsurf, Claude Code, GitHub Copilot, Gentle AI, OpenCode, or any LLM-based coding tool.
- Dump-Driven Knowledge Library —
references/andscripts/are the ACTIVE knowledge library: 48 reference files covering dump-driven audits, Factorio 2.1 breaking changes, DMR lessons, and release/privacy checks — plus 8 audit/analysis scripts (tier progression, locale parity, prototype parsing, privacy scan). - verify_prototype_definition(type, name) tool — Integrated native Function Calling in OpenCode to contrast mod schemas in
data.luaagainst the official JSON specification in real time. - Automated Log Watcher — Asynchronous file watcher on
factorio-current.logthat automatically intercepts stack traces on engine crashes or Lua runtime errors to formulate technical hypotheses before patching. - Strict Pre-Execution Linting — Integrates
luacheckconfigured with thestd+factorioenvironment as a blocking step in the internal CI loop to reject undeclared globals or invalid typing. - 2.0 / Space Age Ready — Full coverage of the 2.0 C++ engine changes, new API signatures, quality system, space platforms, elevated rails, and more.
- Compatibility-First — Namespace conventions, safe inter-mod patterns, dependency management, and conflict detection to prevent mod collisions.
- UPS Optimization — Event filtering, tick throttling, entity tracking patterns, and C++ vs Lua performance tradeoffs.
- Modular Scaffolding Templates — Ready-to-use modular templates for
control.lua,data.lua,settings.lua,info.json, a modulardispatcher.lua, and a semanticmigration.luapipeline.
- Any AI coding assistant that supports custom instructions, system prompts, or agent skill files (Cursor, Windsurf, Claude Code, GitHub Copilot, Gentle AI, OpenCode, or any LLM-based coding tool).
npx skills add Jaer985/factorio-modding-skillThis discovers SKILL.md at the repo root and installs it for your agent (Claude Code, Cursor, Copilot, and 67+ more).
git clone https://github.com/Jaer985/factorio-modding-skill.git ~/.config/opencode/skills/factorio-modding- Clone or download this repository.
- Copy the contents of
SKILL.md(and relevantreferences/files) into your project's.cursorrulesor Windsurf rules file. - Or reference the skill path in your agent configuration.
Include as a reference in your CLAUDE.md or instructions.md:
## Factorio Modding Skill
Reference the factorio-modding skill at /path/to/factorio-modding/SKILL.md
Activate when working with .lua, info.json, or Factorio mod files.
Copy relevant patterns from the references/ library into your .github/copilot-instructions.md or reference the repository in your agent instructions.
Copy the contents of SKILL.md directly into your system prompt or conversation context when working on Factorio mods. You can also include specific references/*.md files as needed.
git submodule add https://github.com/Jaer985/factorio-modding-skill.git .ai/skills/factorio-moddingThe skill activates automatically when working with Factorio mod files. You don't need to manually load it.
| Context | Triggers |
|---|---|
| File patterns | info.json, control.lua, data.lua, settings.lua, data-updates.lua, data-final-fixes.lua, migrations/*.lua, migrations/*.json |
| Keywords | factorio, modding, prototype, recipe, technology, desync, control.lua, data.raw, planet, quality, space-platform, migration |
When the skill is active, the AI will:
- Before writing data-stage prototypes — execute the native
verify_prototype_definition(type, name)tool to validate schema specifications. - Consult the reference library — load the relevant file under
references/for dump-driven audits, Factorio 2.1 breaking changes, and DMR lessons; run thescripts/audits against real data-raw dumps. - Ingest log crash dumps — monitor
factorio-current.logasynchronously to diagnose errors and devises technical hypotheses before patching. - Pass CI Linting — block executions if any undeclared globals or typing violations are caught by
luacheck. - Implement Modular Event Dispatchers — structure mod control files using dispatchers to optimize UPS.
- Integrate Semantic Migration Pipelines — prevent multiplayer desyncs by checking version mutations on
storageinsideon_configuration_changed. - Namespace everything — all prototypes, settings, and remote interfaces will be prefixed with the mod name to avoid collisions.
- Add guards — every
data.rawaccess, remote interface call, and storage read will be safely guarded.
Different tools activate custom instructions in different ways:
| Platform | How to use this skill |
|---|---|
| Any Agent (npx skills) | npx skills add Jaer985/factorio-modding-skill — auto-discovered |
| Cursor | Paste contents into .cursorrules |
| Windsurf | Add to .windsurfrules |
| Claude Code | Reference in CLAUDE.md |
| GitHub Copilot | Add to .github/copilot-instructions.md |
| Any LLM | Paste SKILL.md into conversation context |
The main SKILL.md is the runtime contract. references/ (48 files) and scripts/ (8 audit/analysis scripts) are the active knowledge library — dump-driven audits, Factorio 2.1 breaking changes, DMR lessons, and release/privacy checks:
| Directory | Status | Content |
|---|---|---|
references/ |
ACTIVE | 48 files — audit playbooks, 2.1 breaking changes, compatibility lessons, release & privacy checks |
scripts/ |
ACTIVE | 8 Python scripts — tier progression audit, locale parity, prototype parsing, privacy scan, dump diagnostics |
assets/templates/boilerplate-control.lua |
ACTIVE | Orchestrates modular control flow |
assets/templates/boilerplate-dispatcher.lua |
ACTIVE | Modular event dispatcher template (routes callbacks to minimize loop overhead) |
assets/templates/boilerplate-migration.lua |
ACTIVE | Semantic migration pipeline template (handles version storage updates) |
assets/templates/boilerplate-data.lua |
ACTIVE | Safe prototype definitions with wrapped icons and standard 2.0 trigger syntax |
assets/templates/boilerplate-settings.lua |
ACTIVE | Boilerplate for global and startup settings |
assets/templates/info.json |
ACTIVE | Mod metadata schema |
- ✅ C++ engine changes and API migration
- ✅ Storage (
storage) vs legacyglobal - ✅ Single-table argument API signatures
- ✅ New collision mask format (layers dictionary)
- ✅ Quality system (native C++ in 2.0)
- ✅ Space platforms (
surface.platform) - ✅ Space elevator and planetary logistics
- ✅ Elevated rails
- ✅ Research triggers (no science packs)
- ✅ Fluid system 2.0
- ✅ Data stage:
data.lua,data-updates.lua,data-final-fixes.lua - ✅ Control stage: events, remote interfaces, GUIs
- ✅ Settings: startup, runtime-global, runtime-per-user
- ✅ Prototypes: items, recipes, technologies, entities, fluids
- ✅ Custom planets, quality tiers, audio integration
- ✅ Locale: all section types, UTF-8
- ✅ Migrations: JSON renames and Lua scripts
- ✅ Desync prevention
- ✅ UPS optimization patterns
- ✅ Inter-mod compatibility
- ✅ License compliance
- ✅ Deterministic execution
- ✅ Safe logging and debugging
factorio-modding/
├── SKILL.md # Runtime contract (rules, decision gates, reference index)
├── README.md # This file
├── LICENSE # MIT License
├── references/ # ACTIVE knowledge library — 48 files (audits, breaking changes, lessons)
│ ├── ...
├── scripts/ # ACTIVE audit/analysis scripts — 8 files
│ ├── check-no-private-data.py
│ └── ...
├── assets/
│ └── templates/ # Boilerplate templates
│ ├── boilerplate-control.lua
│ ├── boilerplate-dispatcher.lua
│ ├── boilerplate-migration.lua
│ ├── boilerplate-data.lua
│ ├── boilerplate-settings.lua
│ └── info.json
└── .gitignore
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-improvement - Commit your changes with conventional commits
- Push:
git push origin feature/my-improvement - Open a pull request
Please ensure:
- Frontmatter is valid YAML
- The main
SKILL.mdstays concise (< 1000 tokens) — put depth inreferences/ - All code examples are tested against Factorio 2.0
- Lua patterns follow deterministic and desync-safe practices
MIT — see LICENSE.