How to use the GeoPandas agent skill: install and examples

What the GeoPandas skill makes the agent do

The skill is a set of instructions and reference notes that the agent reads when your task involves GeoPandas objects such as GeoSeries and GeoDataFrame, spatial operations, or reading and writing vector files. Once installed, the agent follows explicit correctness checks: it confirms the coordinate reference system (CRS), checks geometry validity, states the expected join cardinality, and defines what the output must look like before it reports a result.

The skill also includes six bundled local scripts. They inspect files, plan reprojections and exports, audit joins and geometry, and flag privacy-sensitive location fields. They are planning and reporting tools. They do not transform your data, and writing the actual analysis output remains a separate step.

Install the GeoPandas skill from a ZIP file

Download the ZIP for the geopandas skill from this page and unzip it. The folder inside should be named geopandas and contain SKILL.md, a references folder and a scripts folder.

For a personal install that applies to all your projects, place the geopandas folder in ~/.claude/skills/. For a project-only install, place it in the .claude/skills/ folder inside that project. Start a new agent session afterwards so the skill is picked up.

• Personal install: ~/.claude/skills/geopandas/
• Project install: .claude/skills/geopandas/ inside your project folder
• Claude apps: open Settings, go to Capabilities, then Skills, and upload the skill

Check the requirements before you start

The skill targets a pinned GeoPandas stack under Python 3.12 or newer. The source recommends uv to create the environment, then install GeoPandas together with its pinned dependencies: NumPy, pandas, Shapely, pyproj, pyogrio, pyarrow and packaging. Keep optional plotting and PostGIS packages pinned in your project lock as well, and do not mix binary geospatial packages from incompatible package channels.

You need local input files such as shapefiles, GeoPackages or GeoParquet files. The bundled scripts need no API keys or accounts, and they do not use the network.

• Python 3.12 or newer
• uv (recommended for the pinned environment)
• GeoPandas and its pinned dependencies
• Local input files

Trigger the skill with natural requests

You do not need a special command. Describe the GeoPandas task in plain language and name the data you are working with. The skill applies when the work directly uses GeoPandas objects, spatial operations or vector I/O.

Good requests name the file, the goal and any sharing constraint. For example, ask the agent to check the CRS of a local GeoPackage before computing areas, or to audit a spatial join between two local layers and report how many rows matched more than once. If you need a quick web map or a hosted GIS service with no Python analysis, the skill is not the right fit.

• Check whether this shapefile has a CRS and plan a reprojection to a suitable projected CRS for area measurement.
• Audit the spatial join between these two GeoPackages and report unmatched and multiplied rows.
• Before I publish this map, check the point coordinates for sensitive location fields and suggest how to generalize them.

Understand the bundled scripts and the workflow

The agent follows a six-step workflow and uses the scripts at specific points. Each script reports and plans; none of them writes your final analysis output.

• vector_inventory.py inspects a vetted local layer and supports retaining source hashes.
• crs_reprojection_plan.py lists candidate transformations. You then run the transformation yourself with to_crs() or pyproj.
• geometry_validity_report.py audits geometry and can simulate repairs before any new GeoPackage is requested.
• spatial_join_audit.py measures join cardinality. It does not export joined features or dissolve geometries.
• export_plan.py inspects the proposed output contract. A successful plan has not written a file, so write and reopen the output separately.
• sensitive_coordinates_checklist.py helps review disclosure and generalization before you share derived maps or geodata.

Safety notes: scripts, network and untrusted data

The skill runs scripts, so read them before you trust a run and keep the agent's permissions to what the task needs; the skill declares Read, Write, Bash, Glob and Grep as allowed tools. The bundled CLIs are local-only and use an extension allowlist that rejects archives.

The skill does not automatically load URLs, cloud paths, GDAL virtual paths, archives or addresses. Any remote data needs explicit approval, a checked hash and an unpacked local copy. GDAL, PROJ, GEOS and related libraries are native code that parses input, so process untrusted files in a sandbox. Database passwords should come from a secret manager or scoped environment variable, never from a URL or source file.

• Exact coordinates, addresses, parcel boundaries and small-area joins are treated as sensitive by default.
• Macro-enabled office files and nested archives are not opened through permissive drivers.
• PostGIS and tile-provider calls were reviewed against upstream contracts but not tested against a live service.

Tips for getting reliable results

Give the agent the CRS you know from source metadata rather than guessing from coordinate ranges. The skill will not infer a CRS from numbers that look like longitude and latitude, and it will not treat geographic coordinates as metres for buffers, distances or areas.

Ask for a result record. The skill expects source hashes, CRS, operation parameters, predicate, join cardinality and row-count checks for any derived artifact, so requesting them up front saves a round trip.

• Name the expected join type (one-to-one, one-to-many or many-to-many) before a merge or spatial join.
• Keep the original file and write outputs to a new path.
• Reopen every exported file and compare row counts and geometry types.