Instead of manually editing configuration files, you can use AI coding assistants to create and modify GeoEngine workers from natural language prompts. This page provides ready-to-use prompts for popular AI coder tools.
Follow the manual steps first to understand the flow before trying the AI agent route.
Prerequisites
- GeoEngine is installed and logged in
- Docker is running
- An AI coding assistant of your choice (see supported tools below)
| Tool | Provider | How to Use |
|---|
| Claude Code (recommended) | Anthropic | Run from terminal in your script directory |
| Cursor | Cursor | Open your script folder as a project |
| GitHub Copilot | GitHub / OpenAI | Use in VS Code, JetBrains, or CLI |
| Codex | OpenAI | Run from terminal in your script directory |
| Antigravity IDE | Google | Open your script folder as workspace |
| NIKA local agent tooling | Nika | Use inside your local NIKA workspace |
If you have yet to install the skills, follow Installation & Setup to get the skills into your agent.
GeoEngine AI Agent Skills
GeoEngine ships with a built-in AI agent skill that gives your AI coder structured knowledge of the GeoEngine workflow. If you ran geoengine setup skills during installation, the following top-level skill is available to your agent:
| Skill | Description |
|---|
use-geoengine | Master routing skill that handles GeoEngine requests and loads the right internal workflow, module, reference, or CLI command guide. |
use-geoengine, the agent can load focused resources only when needed:
| Internal resource | What it helps with |
|---|
workflows/new-worker.md | End-to-end worker creation: init, script/config/test edits, lint, dev apply, tests, and final apply. |
modules/argparse.md | Adding or repairing Python argparse and R optparse inputs so GeoEngine can pass --name value flags. |
modules/geoengine-yaml.md | Writing or updating the geoengine.yaml worker contract. |
modules/pixi-toml.md | Choosing extra conda-forge dependencies for pixi.toml. |
modules/test-cases.md | Creating or updating tests/geoengine.test.yaml with stable worker tests. |
references/ | Detailed command, YAML, dependency, test, image, cloud, and maintenance guidance. |
With this skill installed, even short prompts like “Make this script a GeoEngine worker” can trigger the full automated workflow.
Step 1: Download the Starter Script
Download the starter script and save it in an isolated folder somewhere on your machine — your home directory or Desktop works fine.
For this example, we will assume you created a directory in /Users/<user>/Downloads/sg-pgpt-gen. Place the script into this directory.
For this example, we will assume you created a directory in C:/Users/<user>/Downloads/sg-pgpt-gen. Place the script into this directory.
For this example, we will assume you created a directory in /home/<user>/Downloads/sg-pgpt-gen. Place the script into this directory.
Step 2: Point the Agent to the Directory
Allow your AI coder access to the directory that contains your script:
- Claude Code / Codex — select the script’s directory as the workspace
- Cursor / GitHub Copilot — open the script’s directory as a project in the IDE
- Antigravity — open the script’s directory as the workspace in the IDE
The AI coder needs to be able to read and write files in that directory to create and edit geoengine.yaml, pixi.toml, and your script.
Step 3: Creating the Worker
Describe your script, its inputs, and its outputs as much as possible. The AI coder will handle the rest — initialising the worker, writing the config files, and building the container.
Prompt Template
I have a(n) [Python/R] script called [script-name] in this directory that [describe what the script does].
Make it a GeoEngine worker called [worker-name] with these inputs and outputs:
Inputs:
- [name]: [type] — [description]
- [name]: [type] — [description]
Outputs:
- [name]: [type] — [description]
[Optional: Mention whether you plan to run it from QGIS or ArcGIS Pro.]
file, folder, string, number, boolean, enum, datetime.
Prompt to Use
Based on the template, you can use the following prompt in your agent.
I have an R script called sg_pgpt_gen.R in this directory that generates polygons and points within Singapore.
Make it a GeoEngine worker called sg-pgpt-gen with these inputs and outputs:
Inputs:
- n-polygons: number - number of polygons to generate
- n-points: number - number of points to generate
- min-sides: number - minimum number of sides per polygon
- max-sides: number - maximum number of sides per polygon
- seed: number - seed for reproducibility
Outputs:
- output-folder: folder — directory where the generated GeoJSON file will be saved
geoengine setup plugins, but individual workers no longer need per-worker plugin flags in geoengine.yaml.
After the agent is done, ensure the following:
- The directory contains all the necessary artifacts.
tests/geoengine.test.yaml exists and contains at least one realistic test case.geoengine lint, geoengine apply --dev, and geoengine test pass.- Running
geoengine workers shows the worker “sg-pgpt-gen”.
You can now test your worker following the steps outlined in the guide. The AI agent
should have done a developmental apply, so you will only find the worker with a “latest” version.
Step 5: Saving a Worker Version
When you are happy with the worker, run a production apply so that the stable version of the script is saved. Run the following in a terminal that is opened to your worker directory.
geoengine lint
geoengine test
geoengine apply
v1.0.0 applied and readily available for you to use.
Step 6: Improving the Worker
Sometimes, you might want to improve on the script. With the help of the AI agent, you can just describe what you want to change.
The AI coder will update the script, config files, and dependencies as needed.
Prompt Template
I have an existing GeoEngine worker in this directory.
[Describe the change you want to make.]
Example
Using the same worker, let’s say that we want to manually specify the bounding box rather than using an automatic bounding box approximation of Singapore.
Use the following prompt to improve on the worker.
I have an existing GeoEngine worker in this directory.
Make the worker take in a parameter of a GeoJSON file that acts as the bounding box, instead of using the hard-coded bounding box.
geoengine test again and then test the “latest” version of the worker in your GIS plugin. Once you are happy with it, feel free to follow
these steps to push the next version to the cloud.
Remember to bump the version number before your next geoengine apply!
Debugging with AI Coder
Here are some prompt templates you can use to debug with your AI coding agent.
Prompt: Fix a Build Failure
My GeoEngine worker failed to build. Here is the error output:
[paste the error output from geoengine apply]
Please diagnose the issue and fix it. Common causes include missing dependencies in pixi.toml, incorrect pixi.toml syntax, or script import errors. After fixing it, run `geoengine lint`, `geoengine apply --dev`, and `geoengine test`.
Prompt: Fix a Runtime Error
My GeoEngine worker builds successfully but fails when I run it. Here is the error:
[paste the error output from geoengine run or the GIS log panel]
Please diagnose and fix the issue. Then run `geoengine lint`, `geoengine apply --dev`, and `geoengine test`.
Prompt: Inspect and Explain a Worker
Explain what this GeoEngine worker does. Read the geoengine.yaml, pixi.toml, and the main script in this directory and give me a summary of:
- What inputs it accepts
- What it does with them
- What outputs it produces
- What dependencies it needs
Tips for Best Results
- Be specific about inputs and outputs — mention file types (
.tif, .geojson, .csv), whether inputs are read-only or writable outputs, and any optional parameters so the AI sets up geoengine.yaml correctly
- Bounce with the agent — AI agents are not perfect. It is unlikely that the agent will succeed on first try. Paste error logs into the prompt to get the agent to fix, before trying again
- Iterate with
--dev — always use geoengine apply --dev during development to skip version checks; run geoengine apply (without --dev) when ready for a production release
- Ask for tests — have the agent create or update
tests/geoengine.test.yaml, then keep geoengine test in the development loop
- Review generated files — check that
geoengine.yaml inputs match your script’s argparse arguments
- Mention GIS plugins — if you need QGIS or ArcGIS Pro support, include that in your prompt (e.g. “enable this for QGIS”)
