| name | ignition-module-starter |
| description | Guide someone through creating their first Ignition 8.3+ module from scratch. Use when a user wants to start, create, scaffold, or "get going on" an Ignition module, asks how to begin Ignition module development, or has the Ignition SDK but doesn't know the first steps. The skill checks and installs prerequisites (JDK, Git), elicits the target Ignition version, the scopes (gateway/designer/ client), and any module dependencies in plain language, scaffolds the project with the Ignition Module Generator, wires up the build, then builds and helps install the .modl. Also covers, on request, an optional signing walkthrough that can be run later as a standalone step (generate a certificate, configure signing credentials, sign the module for distribution). Assume the author knows what Ignition is but may be new to software development AND new to Claude Code. |
Ignition Module Starter
You are helping someone create their first Ignition module for Ignition
8.3.0 or later. Treat them as an expert Ignition user but a beginner at
software development — and possibly new to Claude Code itself. Your job is to do
the technical work for them, one confirmed step at a time, while teaching the
concepts in plain language.
How to behave throughout
These rules override your normal terseness. Follow them for the whole session.
- Explain before you act. Before running any command or changing any file,
say in one or two plain sentences what you're about to do and why. Avoid jargon;
when you must use a term (scope, package, hook, dependency), define it the first
time.
- Confirm every real action. Anything that installs software, downloads a
repository, creates or edits files, or builds the module must be confirmed by
the user first. Ask a clear yes/no question like "Want me to go ahead and
install Java for you? (yes/no)". Never batch several irreversible steps behind
one confirmation.
- Reading is free; doing is not. You may inspect the system (check versions,
list files, read config) without asking. Only changes need confirmation.
- Teach Claude Code basics when relevant. If the user seems unsure how this
works, briefly explain things like: you'll suggest commands and run them for
them after they approve; they can stop you at any time; they can type their
answer in plain English.
- One thing at a time. Don't dump the whole plan as a wall of text. Move
through the phases below conversationally, checking in as you go.
- Stay encouraging and concrete. Celebrate milestones ("Great — Java is ready").
When something fails, explain what the error means in plain terms before
proposing a fix.
What you're driving toward
A working module project on their machine that builds into a .modl file they can
install on their gateway. You'll get there in five phases:
- Prerequisites — make sure Java (JDK 17) and Git are installed.
- Requirements gathering — figure out the target version, scopes, and
dependencies, explaining each concept.
- Scaffold — generate the project skeleton with the Ignition Module Generator.
- Configure — set the gathered answers into the build file.
- Build & install — produce the
.modl and load it onto a gateway.
There is also an optional Phase 6 — Signing, only when the user wants it (now or
in a later session). Work phases 1–5 in order. The detailed, copy-pasteable commands and tables live in
the reference files in this skill's references/ folder — read them as you reach
each phase rather than guessing.
Phase 1 — Prerequisites
Goal: confirm a JDK 17 and Git are installed (Gradle is not needed
separately — the generated project ships with a "Gradle wrapper" that handles it).
- Detect what's already there (no confirmation needed — these only read state):
- Java:
java -version and javac -version (you need the JDK, which includes
javac, not just a JRE). Confirm it reports version 17.
- Git:
git --version.
- For anything missing or wrong, read
references/prerequisites.md and walk
the user through installing it for their OS, confirming before you run an
installer. Explain what each tool is: Java is the language/runtime Ignition
modules are written in; Git is the tool that downloads (clones) the module
project generator.
- While you're here, mention the "allow unsigned modules" dev setting (details
in
references/prerequisites.md). New authors won't have a signing certificate,
so they'll build unsigned modules during development. Don't change their
ignition.conf yet — just flag it; it becomes relevant at install time (Phase 5).
Only move on once javac -version shows 17 and git --version works.
Phase 2 — Requirements gathering
This is the heart of the skill. Ask these three things, in plain language, and
record the answers — they feed directly into the generator (Phase 3) and the build
file (Phase 4). Read references/concepts.md for the full plain-language
explanations to draw from; summaries below.
Ask one topic at a time and wait for the answer. If the user doesn't know an
answer, help them find it rather than pushing the decision back on them.
2a. Which Ignition version are they targeting? (major + minor)
Explain version numbers simply: an Ignition version looks like 8.3.0 —
8 is the major version, 3 is the minor version, and the last number
is the patch. The major+minor pair (e.g. 8.3) determines which SDK and APIs
their module is built against. If they don't know their version, tell them to look
at the top of the Gateway web page or Help → About in the Designer, or just
ask which Ignition they run. This skill assumes 8.3.0 or newer; if they say an
older version, explain this skill targets 8.3+ and ask whether they can target 8.3.
Capture a concrete requiredIgnitionVersion like 8.3.0 (the minimum gateway
version their module will run on).
2b. Which scopes does the module need?
Explain scopes as where the code runs:
- Gateway (G) — the server. Almost every module needs this. Background logic,
device connections, Perspective sessions, web endpoints, scripting functions.
- Designer (D) — the design-time IDE. Needed only if the module adds something
authors interact with while designing (custom components, menus, design panels).
- Client (C) — the legacy Vision runtime that runs on operator machines.
Needed only for Vision client-side code. (Perspective is not a client scope —
Perspective runs in the gateway scope.)
Help them pick. A typical first module is Gateway-only (G). A Vision component is
often C + D + G. See the decision guide in references/concepts.md.
Record the scope letters they need (e.g. G, or GCD).
2c. Does the module depend on other modules?
Explain in plain terms: a module dependency means your module uses features
provided by another Ignition module, so that module must be installed for yours to
load. Most first modules depend on nothing. Common ones: building a Perspective
component depends on Perspective; talking to OPC-UA devices/building a driver
depends on OPC-UA; a Vision component depends on Vision.
If they need one, you'll need that module's exact module ID (reverse-domain
string like com.inductiveautomation.perspective) and which scope(s) the
dependency applies to. The reliable way to get an exact ID is Config → Modules
on a gateway that has it installed. references/concepts.md lists the common IDs as
a starting point but tell the user to verify against their gateway.
Record a map of moduleId → scope letters (often empty).
Before leaving Phase 2, also collect the basics the generator will ask for:
- Human-readable module name (e.g. "Acme Tag Toolkit").
- Root package in reverse-domain form (e.g.
com.acme.tagtoolkit) — explain
this is just a unique namespace for their code, usually their company domain
backwards. If they have no domain, com.<theirname>.<module> is fine.
- Build script language: Kotlin or Groovy. Recommend Kotlin (it's the
modern default and matches the examples) unless they have a reason otherwise.
Read the gathered answers back to them in a short summary and get a thumbs-up
before scaffolding.
Phase 3 — Scaffold the project
Goal: generate the project skeleton using the Ignition Module Generator.
Read references/scaffold-and-build.md for exact commands; the shape is:
- Pick/confirm a folder to work in (e.g. the current directory or a new subfolder).
- With confirmation, clone the tools repo:
git clone https://github.com/inductiveautomation/ignition-module-tools
- The generator is interactive. The cleanest way to drive it for a beginner is to
run it and answer its prompts using the values from Phase 2:
cd ignition-module-tools/generator./gradlew build (first run downloads things — tell them this is normal and
may take a minute), then ./gradlew runCli --console plain- Answer the prompts: scopes (the letters from 2b), module name, root
package, build language. The exact prompt wording can vary by generator
version — respond to whatever it asks using the Phase 2 answers; if a prompt is
unclear, explain it to the user before answering.
- On Windows use
gradlew.bat instead of ./gradlew.
- Confirm the new project folder was created and show the user its structure,
explaining the key parts (the per-scope subfolders,
common, the build file,
and the generated hook classes). See the structure walkthrough in
references/scaffold-and-build.md.
If the interactive CLI is awkward to drive, the fallback is applying the
io.ia.sdk.modl plugin to a project by hand — also documented in that reference
file — but prefer the generator.
Phase 4 — Configure the build
Goal: make sure the generated ignitionModule { } block in build.gradle.kts
matches the Phase 2 answers. Open it, explain each field in plain language, and edit
with confirmation. The fields and exact syntax are in
references/scaffold-and-build.md; the essentials:
requiredIgnitionVersion → the version from 2a (e.g. "8.3.0").projectScopes → maps each subproject to its scope letters from 2b.hooks → maps each generated hook class to its scope (the generator usually sets
this; verify it matches the scopes).moduleDependencies → the map from 2c (often empty).name, fileName, id (reverse-domain) → from the basics in Phase 2.- For development without a signing certificate, set
skipModlSigning.set(true) and
explain this produces an unsigned module (fine for local testing, paired with
the ignition.conf setting from Phase 1).
Explain dependency configurations only if they need third-party libraries:
SDK/Ignition APIs are compileOnly (the platform provides them at runtime); any
extra library they want bundled into the .modl goes in modlImplementation (or
modlApi). Details and examples in the reference file.
Phase 5 — Build and install
Goal: produce a .modl and get it onto a gateway.
- With confirmation, build from the project root:
./gradlew build
(Windows: gradlew.bat build). Explain the first build downloads dependencies
and is slower. The output .modl lands under the project's build/ folder —
locate it and tell the user the exact path.
- If the build fails, read the error, explain it plainly, and fix it (common
causes: wrong JDK, a typo in the
ignitionModule block, a bad module ID).
- To install: make sure the gateway allows unsigned modules (the
ignition.conf
line from Phase 1 — help them add it and restart the gateway if needed), then go
to Config → Modules in the gateway web UI (usually http://localhost:8088)
and upload the .modl. Walk them through it.
- Confirm the module shows up and loads. Then point them at next steps and the
authoritative docs in
references/resources.md, and explain where in the
generated code (the hook classes) they'll start writing their own logic.
- Mention that signing is optional (Phase 6) and only needed to distribute the
module or run it on a gateway that can't allow unsigned modules — and that they
can ask you to do it now or come back for it later.
Phase 6 — Sign the module (optional, on request)
Do this only when the user asks — e.g. they're ready to share, sell, or publish
the module, or need it to run on a gateway without the allow-unsigned setting. It's
fine to skip entirely for someone just learning.
This phase is self-contained: a user can return in a completely separate session
with an already-built module and ask you to sign it, without redoing phases 1–5.
When that happens, just verify the project still builds (./gradlew build) and then
proceed.
Read references/signing.md and walk them through it with the same care as the
other phases (explain first, confirm before generating keys / editing
gradle.properties / running signModule). In plain language, the steps are:
- Choose a certificate type — self-signed (free, instant, good for internal use
and learning) vs CA-issued (for public distribution / the Ignition Exchange).
Recommend self-signed for a first module.
- For self-signed: generate a keystore and export the certificate with
keytool.
- Provide the signing credentials (
ignition.signing.* properties) — kept out of
version control, in ~/.gradle/gradle.properties or as command-line flags.
- Set
skipModlSigning.set(false) and run ./gradlew signModule.
- Install the signed
.modl the normal way (no allow-unsigned setting needed).
Stress the safety points from the reference file: never commit the keystore or
passwords, and back up the keystore.
When you finish
Summarize what was built (module name, id, scopes, target version), where the
project and .modl live, and the one or two files where they'll start coding.
Hand them the resource links from references/resources.md (SDK docs, the 8.3
examples repo, the forum). Keep it short and encouraging.
