reading-portolan
Skill11 starsChanged 32 days agoApache-2.0View on GitHub
Use when exploring, querying, analyzing, or visualizing data from a Portolan catalog (STAC-based cloud-native geospatial data). Covers AGENTS.md and STAC metadata, assets by role, DuckDB queries over GeoParquet and Parquet, COGs, cross-dataset joins, partitioned collections, and interactive maps with PMTiles and MapLibre.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- isaaccorley/geospatial-skillstheir own version, first seen Mar 19, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- isaaccorley/geospatial-skills★ 78same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- catalog-graderSkill
- customize-portolan-browserSkill
- enrich-metadataSkill
- git-backed-catalogSkill
- portolan-bootstrapSkill
- portolan-cliSkill
- portolan-migrateSkill
- portolan-thumbnailsSkill
- register-catalogSkill
- report-catalog-issueSkill
- sourcecoopSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 4 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Check what is installed before you suggest a tool.
- Distinctive: line 36
If nothing is installed, explain the options and offer to guide an install.
- Very specific: line 64
Start at catalog.json. Follow every link with rel: child.
- Very specific: line 73
Every collection links its AGENTS.md with rel: agents and its README.md with rel: describedby.
- Very specific: line 169
When a bbox column exists, filter on it first.
- Very specific: line 211
Check the CRS in DESCRIBE or in the collection metadata before you trust an area or a distance.
- Very specific: line 285
Read windows, not whole files.
- Distinctive: line 291
Use MapLibre GL JS with the PMTiles protocol.
- Very specific: line 320
Read the published style even when you build your own map.
- Very specific: line 332
Use deck.gl only for 3D extrusion or analytical overlays that MapLibre cannot draw.
- Distinctive: line 337
Read the AGENTS.md of each relevant collection.
- Very specific: line 338
Read collection.json. Note the license, the providers, updated, table:columns, and partition:glob.
- Very specific: line 353
Wrong units: Check the CRS. Reproject with ST_Transform or compute in the native CRS.
- Very specific: line 357
Slow query: Add LIMIT. Filter on bbox or an attribute before a spatial predicate.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- drift: depends-on: portolan-spec -->Reading Portolan Data
A Portolan catalog is a STAC catalog served as static files from object storage. Vector data is GeoParquet paired with PMTiles. Raster data is Cloud Optimized GeoTIFF (COG). Tabular data is plain Parquet with no geometry column. There is no API server. You read the JSON, then query the files in place with DuckDB or rasterio.
The Portolan specification is ground truth. Read specs/portolan/core.md and specs/portolan/formats.md at tag v0.2.0 when this skill and a catalog disagree. Rule ids such as PORTO-CORE-061 point into specs/portolan/requirements.yaml.
Step 1: Detect the environment
Check what is installed before you suggest a tool.
duckdb --version
python -c "import duckdb; print(duckdb.__version__)"
python -c "import geopandas; print(geopandas.__version__)"
python -c "import rasterio; print(rasterio.__version__)"
python -c "import rioxarray; print('rioxarray ok')"
gpio --version
ogr2ogr --version| Installed | Vectors and tables | Rasters |
| DuckDB | read_parquet with the spatial and httpfs extensions. Best choice. | Not applicable |
| GeoPandas only | gpd.read_parquet() | Not applicable |
| rioxarray | Not applicable | rioxarray.open_rasterio(). Best choice. |
| rasterio only | Not applicable | rasterio.open() |
| Nothing | Suggest DuckDB | Suggest rioxarray |
If nothing is installed, explain the options and offer to guide an install. Respect a no. Every tool above reads remote files by HTTP range request, so nobody needs to download a whole file first.
Install a current DuckDB with the spatial extension.
Step 2: Read the metadata
Catalog Layout
catalog-root/
├── catalog.json # Root STAC Catalog
├── AGENTS.md # Agent guide, linked as rel: agents
├── README.md # Human guide, linked as rel: describedby
└── {collection_id}/
├── collection.json # Extent, providers, license, assets, links
├── AGENTS.md
├── README.md
├── {data}.parquet # data asset
├── {data}.pmtiles # rel: pmtiles link
├── thumbnail.png # thumbnail asset
├── styles/default.json # style asset with the default role
└── {item_id}/{item_id}.json # one directory per item, when items existEach catalog and each collection includes an AGENTS.md and a README.md (PORTO-CORE-061, PORTO-CORE-062). A versions.json beside them is a CLI artifact, not part of the specification. Ignore it when you read data. There is no llms.txt in the specification.
Crawl the catalog
Start at catalog.json. Follow every link with rel: child. A child with "type": "Catalog" is a sub-catalog, so recurse into it. A child with "type": "Collection" is a dataset. Build the full inventory before you answer a question.
BASE=https://example.com/catalog
curl -s $BASE/catalog.json | jq -r '.links[] | select(.rel=="child") | .href'Read AGENTS.md first
Every collection links its AGENTS.md with rel: agents and its README.md with rel: describedby. Read AGENTS.md before you write a query. It lists the join keys, the coordinate system, the useful aggregations, and the data quality traps. The README documents the schema and the provenance.
COLL=$BASE/collection-id
curl -s $COLL/collection.json \
| jq -r '.links[] | select(.rel=="agents" or .rel=="describedby") | .href'
curl -s $COLL/AGENTS.mdRead collection.json
curl -s $COLL/collection.json | jq '{
id, title, license, updated,
spec: [.stac_extensions[] | select(test("portolan-sdi.org/portolan"))],
bbox: .extent.spatial.bbox,
time: .extent.temporal.interval,
providers: [.providers[] | {name, roles}],
via: [.links[] | select(.rel=="via" or .rel=="canonical") | .href],
pmtiles: [.links[] | select(.rel=="pmtiles") | {href, layers: .["pmtiles:layers"]}],
assets: (.assets | to_entries | map({key, href: .value.href, type: .value.type, roles: .value.roles})),
glob: .["partition:glob"],
columns: [.["table:columns"][]? | {name, type}]
}'Each field reports the following:
stac_extensionscarrieshttps://schemas.portolan-sdi.org/portolan/v0.2.0/schema.json. That URI is the only signal of the specification version (PORTO-CORE-006).licenseis an SPDX identifier, orotherwith arel: licenselink (PORTO-CORE-058, PORTO-CORE-059). Report it before you redistribute anything.providerslists at least oneproducerand exactly onehost, last (PORTO-CORE-047). When the producer and the host are the same organization, the catalog is official. When they differ, the catalog is a mirror.- A mirror has a
vialink (text/html) to the original source (PORTO-CORE-053). It has acanonicallink when the source publishes its own STAC (PORTO-CORE-054). It sets top-levelupdatedto the last sync time (PORTO-CORE-057). Compareupdatedwith the source when freshness matters. table:columnsdocuments the columns with names, types, and descriptions. Read it beforeDESCRIBE.partition:globis present only on a partitioned collection. See Step 4.
Find assets by role
An asset key means nothing. Filter on roles (PORTO-CORE-027). Each asset has a type and at least one role (PORTO-CORE-025).
| Role | What it is | Media type |
data | The primary GeoParquet, Parquet, or COG | application/vnd.apache.parquet or image/tiff; application=geotiff; profile=cloud-optimized |
collection-mirror | items.parquet, a stac-geoparquet copy of the items | application/vnd.apache.parquet |
style | A MapLibre GL style. One also carries default. | application/vnd.mapbox.style+json |
visual | The PMTiles file, when it is also a distribution asset | application/vnd.pmtiles |
thumbnail | Preview image | image/png, image/jpeg, or image/webp |
source | The upstream original a mirror converted from | Any |
curl -s $COLL/collection.json \
| jq -r '.assets | to_entries[] | select(.value.roles | index("data")) | .value.href'Hrefs are relative to the file that holds them. An absolute asset href uses https (PORTO-CORE-023). An asset may add an s3:// or gs:// URL under alternate (PORTO-CORE-024). Use the https href with DuckDB unless you have bucket credentials. Do not rewrite an https URL into s3:// by hand.
Asset hrefs and access paths
- A single-file vector, tabular, or single-COG collection puts its
dataasset on the collection (PORTO-CORE-017). - A raster collection with several scenes puts one COG on each item. Items live at
{item_id}/{item_id}.json. The collection should also publishitems.parquetwith thecollection-mirrorrole (PORTO-FMT-040, PORTO-FMT-041). Query that file to find scenes instead of fetching every item JSON. - A partitioned vector collection puts its files behind
partition:glob(PORTO-FMT-019). It may also list partitions as items. - A tabular collection is a Parquet
dataasset with no geometry column (PORTO-FMT-034). Itsextent.spatial.bboxis the area the table refers to, not a footprint. When geometry and attributes live in separate files, the README documents the join columns and carries a working join example (PORTO-FMT-038). Copy that example.
Step 3: Query vectors and tables with DuckDB
INSTALL spatial; LOAD spatial;
INSTALL httpfs; LOAD httpfs;For a private s3:// bucket, set s3_region, s3_access_key_id, and s3_secret_access_key before you read.
Explore before you query
-- Schema. Compare with table:columns.
DESCRIBE SELECT * FROM read_parquet('https://.../data.parquet') LIMIT 0;
-- Row count. Reads the footer only.
SELECT count(*) FROM read_parquet('https://.../data.parquet');
-- Always LIMIT during exploration.
SELECT * FROM read_parquet('https://.../data.parquet') LIMIT 10;
-- Sample values for a column.
SELECT DISTINCT column_name FROM read_parquet('https://.../data.parquet') LIMIT 20;Use the file layout
Portolan GeoParquet follows rules that make remote queries cheap:
- Rows are spatially ordered (PORTO-FMT-006). Hilbert order is common, but it is one scheme among several. Do not assume a specific curve.
- Each file has per-row-group spatial statistics (PORTO-FMT-007). A GeoParquet 1.1 file has a
bboxcovering column with min and max statistics. A GeoParquet 2.x file may have native geometry statistics and nobboxcolumn. CheckDESCRIBEbefore you referencebbox. - Row groups hold at most 150,000 rows (PORTO-FMT-009). A spatial or attribute filter skips whole groups from metadata.
- Files are compressed,
zstdby default.
When a bbox column exists, filter on it first. The filter prunes row groups without parsing geometry.
SELECT * FROM read_parquet('https://.../data.parquet')
WHERE bbox.xmin > 5.0 AND bbox.xmax < 6.0
AND bbox.ymin > 52.0 AND bbox.ymax < 53.0
LIMIT 100;Refine with the geometry only after the bbox pass:
SELECT * FROM (
SELECT * FROM read_parquet('https://.../data.parquet')
WHERE bbox.xmin > 5.0 AND bbox.xmax < 6.0
AND bbox.ymin > 52.0 AND bbox.ymax < 53.0
)
WHERE ST_Intersects(geometry, ST_MakeEnvelope(5.0, 52.0, 6.0, 53.0));Without a bbox column, use ST_Intersects directly. DuckDB still prunes on native statistics where the file has them.
Common patterns
-- Attribute filter and aggregation
SELECT province, sum(population) AS total_pop, count(*) AS n
FROM read_parquet('https://.../data.parquet')
WHERE year >= 2020
GROUP BY province ORDER BY total_pop DESC;
-- Area and distance. Units follow the CRS.
SELECT name, ST_Area(geometry) AS area FROM read_parquet('https://.../polygons.parquet')
ORDER BY area DESC LIMIT 10;
-- Point in polygon
SELECT p.name, r.name AS region
FROM read_parquet('https://.../points.parquet') p
JOIN read_parquet('https://.../regions.parquet') r
ON ST_Within(p.geometry, r.geometry);Check the CRS in DESCRIBE or in the collection metadata before you trust an area or a distance. A projected CRS gives meters. EPSG:4326 gives degrees.
Cross-collection joins
Collections in one catalog share a base URL, so a join across them is one query. Read each collection's AGENTS.md for the join key first. An attribute join on a documented key runs faster than a spatial join.
-- Which park holds the most buildings?
SELECT parks.name, count(*) AS building_count
FROM read_parquet('https://.../parks/parks.parquet') parks
JOIN read_parquet('https://.../buildings/buildings.parquet') b
ON ST_Within(b.geometry, parks.geometry)
GROUP BY parks.name ORDER BY building_count DESC;Large spatial joins are slow. Filter each side with a WHERE clause or a bbox pass first. Materialize a filtered subset with CREATE TABLE subset AS SELECT ..., then join the subset.
Export
COPY (SELECT * FROM read_parquet('https://.../data.parquet') WHERE ...)
TO 'subset.parquet' (FORMAT PARQUET, COMPRESSION ZSTD);
COPY (SELECT * FROM read_parquet('https://.../data.parquet') WHERE ...)
TO 'subset.geojson' WITH (FORMAT GDAL, DRIVER 'GeoJSON');For other formats use ogr2ogr. It reads remote files through /vsicurl/https://..., /vsis3/bucket/..., and /vsigs/bucket/.... gpio inspect data.parquet and gpio inspect stats data.parquet summarize a file without SQL. gpio check all data.parquet reports whether a file follows the layout rules above.
Step 4: partitioned collections
A collection with partition:glob spreads its rows over several files. The glob is the bulk-access path (PORTO-FMT-019). Copy it as written. Do not build your own pattern from the asset hrefs, because the scheme determines the directory layout.
The glob may use s3:// or gs:// even though asset hrefs use https (PORTO-FMT-020). Glob expansion needs a bucket listing, and plain https cannot list. DuckDB does not expand an https glob.
-- Public GCS bucket: an anonymous secret is enough.
LOAD httpfs;
CREATE SECRET (TYPE gcs);
-- Copy partition:glob from collection.json.
SELECT count(*) FROM read_parquet(
'gs://bucket/catalog/collection/quadkey_prefix=*/*.parquet'
);
-- Explore one partition first.
SELECT * FROM read_parquet(
'gs://bucket/catalog/collection/quadkey_prefix=00/*.parquet'
) LIMIT 10;
-- Hive-style paths prune on the partition key.
SELECT * FROM read_parquet(
'gs://bucket/catalog/collection/quadkey_prefix=*/*.parquet',
hive_partitioning = true
) WHERE quadkey_prefix = '00';For s3://, set the region and, for a private bucket, the keys. Every partition file shares one schema (PORTO-FMT-021), so the glob queries as one table. When the partitions are also items, items.parquet or the item JSONs give each partition's bbox.
Step 5: read rasters
One COG is a collection data asset. A multi-scene collection has one item per scene. Query items.parquet (role collection-mirror) with DuckDB to select scenes by bbox or datetime, then open the COG href from the chosen rows.
Each band of a Portolan COG has an embedded minimum, maximum, mean, and standard deviation (PORTO-FMT-027). They are in the leading header block, so one range request returns them. Read them from the tags. Do not compute statistics from pixels.
import rasterio
with rasterio.open("https://example.com/catalog/collection/scene.tif") as src:
print(src.crs, src.bounds, src.res, src.count, src.nodata)
for band in range(1, src.count + 1):
print(band, src.tags(band)) # STATISTICS_MINIMUM, _MAXIMUM, _MEAN, _STDDEVRead windows, not whole files. rioxarray.open_rasterio(url) is lazy. da.isel(x=slice(0, 512), y=slice(0, 512)).compute() fetches only the tiles that window touches. Use src.overviews(1) and a decimated read for a whole-extent preview.
For conversion, gdal_translate and gdalwarp read the same /vsicurl/ URLs as ogr2ogr. Point cloud support is not yet defined in the specification (PORTO-FMT-039). Do not promise COPC support.
Step 6: visualize
Use MapLibre GL JS with the PMTiles protocol. Do not export GeoJSON or inline data for a web map. The collection already provides tiles built for the browser.
Find the tiles
PMTiles is a collection-level link with rel: pmtiles and type application/vnd.pmtiles (PORTO-FMT-011). Its pmtiles:layers array names the layers a client shows by default (PORTO-FMT-012). Those names are the source-layer values for MapLibre. Do not guess the layer name from the file name. An asset with the visual role may use the same file when the publisher also offers it for download.
curl -s $COLL/collection.json \
| jq '.links[] | select(.rel=="pmtiles") | {href, layers: .["pmtiles:layers"]}'pmtiles show data.pmtiles --metadata prints the full layer list from a local or remote archive.
Use the published style
A collection with PMTiles carries at least one style asset (PORTO-FMT-014). Filter assets on the style role (PORTO-CORE-069). When there are several, exactly one also carries default (PORTO-CORE-070). Each style is a complete MapLibre GL style, version 8, with media type application/vnd.mapbox.style+json (PORTO-FMT-015). Its sources.data.url is a path relative to the styles/ directory, usually ../{name}.pmtiles. Resolve it against the style URL before you load it.
curl -s $COLL/collection.json \
| jq '.assets | to_entries[] | select(.value.roles | index("style")) | {key, href: .value.href, roles: .value.roles}'Reference files in this skill:
reference/style-default.jsonshows the shape of a published style.reference/map-style.htmlloads a style asset and resolves its PMTiles URL. It also switches between styles.reference/map-inline.htmlbuilds a style inline when the collection provides none. It takes the PMTiles URL and thesource-layerfrom therel: pmtileslink.reference/map-multi.jsdraws two collections on one map.
Read the published style even when you build your own map. It has the right source-layer, a palette matched to the attribute values, and the match and filter expressions that show which values exist.
Data-Driven Styling
MapLibre expressions style by attribute:
"fill-color": ["match", ["get", "category"], "residential", "#4361ee", "commercial", "#e63946", "#999999"]
"fill-opacity": ["interpolate", ["linear"], ["get", "value"], 0, 0.1, 100, 0.9]
"filter": ["==", ["get", "status"], "active"]Use deck.gl only for 3D extrusion or analytical overlays that MapLibre cannot draw. Its MVTLayer reads the same PMTiles file. For a COG on a web map you need a tile server. Rendering rasters in the browser is out of scope for this skill.
Workflow: Answer a question about a catalog
- Crawl
catalog.jsonand every sub-catalog. List the collections. - Read the
AGENTS.mdof each relevant collection. - Read
collection.json. Note the license, the providers,updated,table:columns, andpartition:glob. - Pick the
dataasset by role, or copypartition:glob, or queryitems.parquet. - Explore with
DESCRIBE,count(*), andLIMIT 10. - Answer with one DuckDB query. Filter before you join.
- For a map, use the
rel: pmtileslink and thedefaultstyle asset. - Report the license and, for a mirror, the
viasource and theupdatedtime.
Troubleshooting
403 or 404 on a data URL. Confirm the href resolves against the file that holds it, not against the catalog root. A private bucket needs credentials. Do not turn an https href into s3:// by hand.
Glob returns nothing or errors. You used an https glob. Copy partition:glob from collection.json and configure the bucket scheme it uses.
Column not found. Column names are case sensitive. Read table:columns and DESCRIBE. The geometry column is usually geometry, but confirm it. A file without a bbox column is GeoParquet 2.x with native statistics.
Wrong units. Check the CRS. Reproject with ST_Transform or compute in the native CRS.
Empty map. The source-layer does not match pmtiles:layers, or the style's relative pmtiles:// URL was not resolved against the style file's URL.
Slow query. Add LIMIT. Filter on bbox or an attribute before a spatial predicate. Query one partition first. Check file:size on the asset before a full scan.
Memory pressure. DuckDB streams. For GeoPandas, pass columns= and a bbox= filter. For rasters, read windows.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

