geoai-skills

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.

_{These figures describe the shipped tree, on one runtime/model pair — Claude Code 2.1.214 with claude-sonnet-5, 167-case suite efe27d8c1736…, 2026-08-05 — and are not universal or model-independent claims. Routing measures which skill activates, not whether the answer is correct; answer quality has never been measured. The run that produced these numbers also recorded one false positive and two cases that moved from pass to fail without an established cause. See BENCHMARK.md for the full card, the reviewed failures, and what the run does not show.}

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.

An 18-skill, 167-case Claude Code run recorded 99.17% routing precision, 96.77% routing recall, and 96.41% full-route accuracy on suite efe27d8c1736… under Claude Code 2.1.214 with claude-sonnet-5 (2026-08-05). The paired skills-disabled control produced zero activations across all 167 cases. All four false negatives, the one false positive, and all eleven max_turns execution errors were inspected; every enabled error had its activation recovered from the raw trace, none lost, so the enabled routing metrics are unaffected. Behavior quality remains unclaimed until independent-family judging and the manual-review protocol are complete.

This run was bought to test a published defect, and it also found new ones. The previous card attributed four of its nine false negatives to one clause in the change-detection description and shipped the fix as a hypothesis. All four of those cases now route correctly, both over-correction guards held, and the control arm is clean. Against that: one boundary probe still misroutes, and two cases that previously passed now fail without a cause the diff can explain — run-to-run variance and a real regression are indistinguishable from a single run. The suites are also different populations (158 → 167 cases), so the figures above are not a before/after ratio; the honest comparison is case-level and is in the card.

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.

npx skills add muend/geoai-skills --list

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

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

python tools/build_openai_plugin_bundle.py

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

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

/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.

python tools/build_skill_archives.py

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.