GeoAI Skills

The correctness layer for geospatial AI agents

Stop silent CRS, spatial-leakage, validity, unit, and uncertainty failures before
they ship.

GeoAI Skills is a vendor-neutral collection of 18
Agent Skills that turns a general-purpose AI agent into a
more defensible geospatial collaborator. It covers the full workflow—from STAC
search and PostGIS to spatial statistics, Earth observation, LiDAR, cartography,
and guarded ArcGIS Pro automation—while making verification and limitations part
of the deliverable.

A plausible shortcut is not a defensible result.
Watch the short MP4 · View the static verdict · Install · Inspect the evidence

The demo uses a public, synthetic prompt. It shows the intended guardrail behavior,
not a claim that every model or runtime will produce identical wording.

Quick start

Install the complete suite for Codex:

npx skills add muend/geoai-skills --skill '*' -a codex

Or install one specialist for Claude Code:

npx skills add muend/geoai-skills \
  --skill remote-sensing-analysis \
  -a claude-code

Then ask naturally:

Can May 2024 and September 2025 Sentinel-2 scenes support a defensible
changed-hectares claim?

The relevant skills should activate automatically. Instead of blindly subtracting
two rasters, the agent is instructed to test comparability, identify the
phenological mismatch, withhold an unsupported area claim, and specify the evidence
needed to proceed.

What changes when the skills are present

These skills complement MCP servers, GIS libraries, and hosted tools. They are the
method and verification layer that tells an agent when not to trust an apparently
successful operation.

Why this exists

Spatial bugs are unusually quiet:

• a buffer computed in degrees still returns numbers;
• a random spatial train/test split still produces a beautiful learning curve;
• a misregistered change map still shows crisp-looking boundaries;
• overlapping polygons can silently inflate an area total;
• an attractive choropleth can still encode the wrong class semantics.

General-purpose models often know the APIs. The harder problem is knowing which
preconditions, controls, and refusal conditions make a geospatial claim defensible.
GeoAI Skills encodes that discipline:

• CRS and units are explicit.
• Spatial leakage is treated as a default risk.
• Every stage ends with numeric and visual verification.
• Uncertainty and sensitivity are outputs, not optional footnotes.
• Missing evidence narrows or blocks the claim instead of being guessed.

Evidence with boundaries

The current source tree contains two deliberately separate evaluation layers:

The external subset is independently authored and reported separately. It does not
copy upstream datasets, prompts, or reference implementations, and its outcomes must
not be pooled with native routing metrics. Its five-case v1 source population is
frozen under suite hash c99563100cac…; a separate v2 contract freeze distinguishes
semantic correctness, evidence sufficiency, and exact representation compliance
without changing those cases. Frozen producer interface v1 preserves the first
shape-only condition; v2 adds answer-safe method, serialization, UTF-8, and
workspace execution guidance after observed cross-runtime ambiguities, without
exposing reference values. The separately frozen v3 condition pairs a semantic
validator with fully disclosed nested output structures, bounded floating-point
tolerance, exact inventory checks, and representation-independent map checks;
historical v1/v2 evidence remains unchanged. Every deterministically rendered
prompt is hashed.
Results follow the
offline run and result protocol,
which reports skill activation, runtime completion, artifact-contract compliance,
and overall success as separate measures.

A current 18-skill, 158-case Claude Code run recorded 100% routing precision,
92.37% routing recall, and 93.67% full-route accuracy on suite
f03e327a57d2… under Claude Code 2.1.214 with claude-sonnet-5 (2026-08-04).
The paired skills-disabled control produced zero activations across all 158
cases. All nine false negatives and all seven max_turns execution errors were
inspected; the errors had already recorded their correct activation and so do not
affect routing metrics. Behavior quality remains unclaimed until
independent-family judging and the manual-review protocol are complete.

Read BENCHMARK.md for the full result card and
EVALUATION.md for the provider-neutral protocol, suite hashes,
split rules, judge boundaries, and publication gates.

The 18-skill stack

Install the full suite for cross-skill routing, or cherry-pick a specialist. Every
skill must remain safe and useful alone; sibling references are advisory and
critical safeguards have local fallbacks.

Installation

Choose the surface you already use.

Browse the collection on skills.sh
or inspect it without installing:

npx skills add muend/geoai-skills --list

Install all 18 skills for Claude Code:

npx skills add muend/geoai-skills --skill '*' -a claude-code

Install all 18 skills for Codex:

npx skills add muend/geoai-skills --skill '*' -a codex

Run npx skills add muend/geoai-skills without flags for the interactive agent
and skill picker.

Version 0.2.0 is published in the OpenAI Plugins Directory as GeoAI Skills.
The repository is a skills-only plugin: it adds no hosted service, authentication
flow, or MCP server.

Build the deterministic upload archive:

python tools/build_openai_plugin_bundle.py

The ignored dist/ output contains only the plugin manifest, public policy pages,
logo, and runtime skill files. Evaluation cases, benchmark traces, repository
automation, and private development material are excluded.

From a terminal:

claude plugin marketplace add muend/geoai-skills
claude plugin install geoai@geoai-skills

From an interactive Claude Code session:

/plugin marketplace add muend/geoai-skills
/plugin install geoai@geoai-skills

Installed skills use the stable geoai namespace, for example:

/geoai:remote-sensing-analysis

GitHub Copilot

GitHub Copilot can load project skills from .github/skills, .claude/skills,
or .agents/skills. With GitHub CLI 2.90.0 or later, preview before installing:

gh skill preview muend/geoai-skills remote-sensing-analysis
gh skill install muend/geoai-skills remote-sensing-analysis

The Skills CLI also provides an explicit Copilot target:

npx skills add muend/geoai-skills \
  --skill remote-sensing-analysis \
  -a github-copilot

See GitHub's
Agent Skills documentation
for supported locations, pinning, provenance, and security guidance.

For Claude.ai or Claude desktop, download individual skill ZIP files and
SHA256SUMS from the latest GitHub Release, then upload them through
Customize → Skills → Create skill → Upload a skill.

To build the same deterministic archives locally:

python tools/build_skill_archives.py

Any Agent-Skills-compatible runtime can instead copy directories from skills/
into its skills directory. Real arcgis-pro-automation execution additionally
requires Windows, licensed ArcGIS Pro, and a configured local
arcgis-mcp-bridge.

Release maintainers should use RELEASING.md for the
non-publishing candidate workflow, clean-install matrix, evidence requirements,
publication gate, and rollback procedure.

Try these prompts

Reject an invalid change claim

Plan a defensible two-date Sentinel-2 forest-loss workflow. One scene is from
May 2024 and the other from September 2025. Decide whether this comparison can
support a changed-hectares claim.

Expected intervention: identify the phenology mismatch; withhold the hectare
claim; request matched-season imagery or a season-aware time series; require
registration, mutual masks, sensitivity analysis, and error-adjusted area
uncertainty.

Make spatial SQL measurable and index-safe

Design production-safe PostGIS SQL to return flooded area in hectares per
parcel for two large EPSG:4326 polygon tables. Include invalid-geometry
handling and an EXPLAIN verification plan.

Expected intervention: select a suitable projected measurement CRS, avoid
transforming indexed columns inside predicates, repair derived working geometry,
deduplicate overlaps, and verify the query plan.

Refuse inconsistent suitability weights

Use this AHP pairwise matrix to build a solar-suitability map. Its consistency
ratio is 0.19.

Expected intervention: reject the weights before mapping, identify discordant
judgments, require revision, and preserve sensitivity analysis as a deliverable.

How it works

1. Trigger narrowly. Specialist descriptions identify the domain decision
   that owns the task; negative and collision cases test over-triggering.
2. Load progressively. The agent reads only the relevant SKILL.md, then
   loads references or scripts when required.
3. Enforce invariants. CRS, validity, leakage, units, uncertainty,
   provenance, verification, and failure behavior travel across the workflow.
4. Route across specialists. The orchestrator coordinates genuine
   multi-stage work without replacing specialist judgment.
5. Fail loudly. Missing inputs produce a narrower claim, provisional plan,
   clarification, or refusal—not invented evidence.

Design principles

1. Fail-loud spatial computing. Successful execution is not proof of a valid
   geographic result.
2. Methodological honesty. Uncertainty, multiple-testing correction,
   sensitivity, and error-adjusted estimates are first-class outputs.
3. Anti-leakage by default. Spatial and grouped validation replace random
   splits whenever geographic generalization is claimed.
4. Tool-pragmatic, vendor-neutral guidance. Open Python, PostGIS/DuckDB,
   Earth Engine, ArcGIS, and other backends are selected by evidence and scale.
5. Progressive disclosure. Long references and scripts cost no context until
   the task actually needs them.
6. Measured, not assumed. Source cases, run evidence, suite hashes, errors,
   costs, limitations, and superseded results are kept distinguishable.

geoai-skills/
├── skills/<skill-name>/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   ├── scripts/
│   └── references/
├── evals/cases/<skill>/       # native development-only cases
├── evals/external/            # separately reported transfer suites
├── tools/                     # validators, adapters, builders, and gates
├── benchmarks/                # immutable published evidence packages
├── .codex-plugin/             # OpenAI skills-only plugin manifest
├── .claude-plugin/            # Claude marketplace and plugin manifests
├── BENCHMARK.md               # published result card and limitations
├── EVALUATION.md              # provider-neutral evaluation protocol
├── CASE_STUDIES.md            # evidence policy and accepted cases
└── RELEASING.md               # release and rollback runbook

Contributing

Contributions are welcome. Start with CONTRIBUTING.md.
A skill change should:

• pass the structural and link validators;
• add or update evaluation cases;
• avoid duplicating canonical cross-cutting rules;
• define verification and failure behavior; and
• keep runtime packages free of benchmark and private development material.

Real-world catches belong in CASE_STUDIES.md only when they
include a dated, privacy-safe reproducer, comparison evidence, verification
method, and limitations.

License

MIT — use it, fork it, and ship it. If GeoAI Skills prevented a
silent spatial failure, a ⭐ helps the next practitioner find it.