---

name: io-formats description: "Use when reading, writing, filtering, converting, or troubleshooting GeoPandas vector files, GeoJSON, WKB/WKT, Arrow, Parquet, Feather, and PostGIS data." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

I/O and Formats

Use this sub-skill when the task is about moving geospatial vector data into or out of GeoPandas, choosing a storage format or engine, preserving CRS/geometry metadata, or diagnosing optional I/O dependencies.

Read First

• I/O reference: verified signatures and behavior notes for read_file, to_file, Arrow/Parquet/Feather, WKB/WKT, GeoJSON-like records, and SQL/PostGIS APIs.
• Workflows: recipes for safe file round trips, filtered reads, GeoParquet/Feather decisions, WKT/WKB conversions, and PostGIS handoffs.
• Troubleshooting: symptoms and fixes for missing pyarrow, Fiona/pyogrio engine differences, CRS metadata loss, SQL service errors, and unsupported drivers.
• io_roundtrip_smoke.py: tiny temporary GeoDataFrame round-trip check for GeoJSON or GPKG.
• check_optional_io_dependencies.py: optional dependency reporter for I/O, database, visualization, and geocoding packages.

Route Here When

• The user asks for geopandas.read_file, GeoDataFrame.to_file, list_layers, engine="pyogrio", engine="fiona", file drivers, archive/URL reads, bbox, mask, columns, or rows filters.
• The task involves GeoJSON dictionaries, __geo_interface__, iterfeatures, to_json, or to_geo_dict.
• The task mentions read_parquet, to_parquet, read_feather, to_feather, to_arrow, from_arrow, GeoParquet, GeoArrow, pyarrow, or covering bbox metadata.
• The task needs GeoSeries.from_wkt, to_wkt, from_wkb, to_wkb, or tabular geometry serialization.
• The task uses read_postgis, to_postgis, SQLAlchemy connections, PostGIS geometry columns, or database write policies.

Route Elsewhere

• Use ../core-data-model/SKILL.md for geometry-column repair, CRS assignment versus reprojection, and object semantics before or after I/O.
• Use ../spatial-operations/SKILL.md for analysis after loading layers.
• Use ../mapping-geocoding/SKILL.md for plotting/geocoding after loading data.
• Use ../validation-testing/SKILL.md when designing assertions for I/O results or selecting native tests.

Default Operating Rules

1. Prefer the base pyogrio engine when available; use Fiona only when the task specifically needs Fiona behavior or installed environment supports it.
2. Preserve and validate CRS after every round trip. File formats and engines differ in metadata support.
3. Use columns, rows, bbox, or mask filters to reduce read size before expensive analysis.
4. Treat Parquet/Feather/Arrow as optional pyarrow workflows; provide a GeoJSON/GPKG fallback when pyarrow is unavailable.
5. Treat PostGIS as a service-backed workflow: Python imports are not enough; a live database, credentials, schema privileges, and geometry column conventions are required.
6. Never assume a file driver from extension alone when a task has strict format requirements; set driver= for writes when needed.

Minimal Checks

python scripts/io_roundtrip_smoke.py --format geojson
python scripts/check_optional_io_dependencies.py --json

Expected signals: the round trip returns the expected row count, CRS, geometry column, and file path suffix in a temporary directory; the dependency checker reports missing optional modules without failing unless --require is used.

Handoff

• After data is loaded, route CRS and active geometry validation to core-data-model when needed.
• For joins, overlays, clips, dissolves, and metric operations, route to spatial-operations.
• For final equality checks or test fixtures, route to validation-testing.