What geospatial file formats does this skill support?

The skill supports various vector formats including GeoJSON, Shapefile, GeoPackage, KML/KMZ, FlatGeobuf, and CSV with geometry.

What are the prerequisites for using this skill?

You need to have a scaffolded PortalJS portal, and native CLIs for GDAL, tippecanoe, and DuckDB installed on your machine.

Can I use this skill for raster data formats?

No, this skill is specifically designed for vector formats and does not support raster data formats.

What happens if my geospatial file is too large?

The skill includes a size escape hatch that warns if the normalized GeoJSON exceeds 500 MB, and it will skip PMTiles for files larger than 2 GB.

How does the skill handle errors during ingestion?

The skill provides detailed error messages for various issues, such as missing tools or unsupported formats, guiding users on how to resolve them.

PortalJS Add Geo

Name: PortalJS Add Geo
Availability: InStock
Author: jeremylongshore

Free

Seamlessly ingest geospatial files into PortalJS.

by jeremylongshore2.6k stars on jeremylongshore/claude-code-plugins-plus-skills

1 views

Updated Aug 10, 2026

Get this skill

Free · Opens the source repo

What PortalJS Add Geo does

PortalJS Add Geo is a skill designed for developers and data professionals who need to integrate geospatial data into their PortalJS applications without relying on server-side processing. This skill automates the ingestion of various geospatial file formats, including GeoJSON, Shapefile, and GeoPackage, transforming them into a dual-tier dataset that can be rendered and queried seamlessly on the user's local machine. The process is entirely serverless, ensuring that users maintain full control over their data while leveraging the capabilities of PortalJS.

When a geospatial file is uploaded, the skill normalizes the coordinate reference system to EPSG:4326, which is a widely used geographic coordinate system. It then generates two key outputs: a PMTiles render tier for efficient map rendering and a GeoParquet query tier for executing spatial SQL queries. Both of these outputs are stored in Cloudflare R2, allowing for easy access and management. Additionally, the original file is preserved in its native format, ensuring that users have access to the original data if needed.

This skill is particularly useful for users who work with vector geospatial formats and require a quick and efficient way to prepare their data for visualization and analysis. By automating the manual steps typically involved in preparing geospatial datasets, PortalJS Add Geo saves time and reduces the potential for errors during the data preparation process. It is ideal for developers looking to enhance their geospatial applications and for data scientists needing to perform spatial queries on their datasets.

However, users should ensure they have the necessary dependencies installed on their machines, such as GDAL, tippecanoe, and DuckDB, as the skill will not function without them. Additionally, while the skill handles a variety of geospatial formats, it is not suitable for raster formats or unsupported vector formats, which may require alternative solutions.

When to use it

Use this skill when you need to quickly ingest vector geospatial files into a PortalJS portal without server-side processing.

When not to use it

This skill is not suitable for raster data formats or unsupported vector formats, and it requires specific native tools to be installed on your machine.

What you can build with it

Ingesting a GeoJSON file

Use the skill to upload a GeoJSON file of rivers, creating both PMTiles and GeoParquet outputs for visualization and querying.

Uploading a zipped Shapefile

Ingest a zipped Shapefile from a URL to automatically generate the necessary dual-tier datasets for your PortalJS application.

Handling a GeoPackage with multiple layers

Use the skill to specify a layer from a GeoPackage, allowing for targeted ingestion and processing of geospatial data.

How to install PortalJS Add Geo

View source

1. Install with the skills CLI

npx skills add jeremylongshore/claude-code-plugins-plus-skills/portaljs-add-geo --agent claude-code

2. Or install it manually

Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.

Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs

Inside SKILL.md

Written by jeremylongshore

PortalJS — Add Geo

Overview

Turn one geospatial upload into a dual-tier PortalJS dataset entirely on the user's machine — no server-side container compute, keeping the zero-backend bet end-to-end. From a single source the skill derives two serverless tiers plus the preserved original:

PMTiles (render tier) — a vector-tile archive <MapPreview> renders with MapLibre GL over HTTP range requests; any dataset size pans and zooms with no tile server.
GeoParquet (query tier) — a GeoParquet 1.1 file (covering bbox column, Hilbert-sorted) <GeoQuery> runs spatial SQL over in place via DuckDB-Wasm.
Original — the untouched upload in its native CRS, kept downloadable.

All three land on Cloudflare R2 (Git LFS → Giftless), and the skill appends one datasets.json entry whose resources[] match the shape the showcase auto-renders (the @reference/world-boundaries demo, PR #1647): pmtiles → <MapPreview>, geoparquet → <GeoQuery>, original → download. No page edits are needed. It automates the manual tippecanoe/duckdb recipes in the template README.

Prerequisites

A scaffolded portaljs-catalog portal whose template ships components/MapPreview.tsx and components/GeoQuery.tsx (PR #1647 or later).
Native CLIs on the user's machine: GDAL (ogr2ogr, ogrinfo), tippecanoe, and duckdb (with the spatial extension). macOS: brew install gdal tippecanoe duckdb; Debian/Ubuntu: apt-get install gdal-bin duckdb + tippecanoe (apt or build from source); Windows: use WSL. The skill hard-stops with the install hint if any is missing.
Arc credentials for the Git-LFS → R2 push (the same token portaljs-deploy resolves), or an OSS self-hosted Giftless.

Instructions

The canonical, full step-by-step workflow is .claude/commands/portaljs-add-geo.md — the single source of truth. Read and follow it when executing. Summary:

Gather input — source (geo file path or URL), portal directory, namespace. Interview if missing; never dead-end.
Detect the native tools (ogr2ogr, tippecanoe, duckdb + spatial). Any missing → print the per-OS install and stop.
Validate the portal directory and confirm the geo showcase components exist.
Fetch (if URL) and detect the input format; reject raster and bare .shp.
Preserve the original, then normalize to EPSG:4326 GeoJSON with ogr2ogr -t_srs EPSG:4326.
Apply the size escape hatch (measure normalized-GeoJSON bytes): warn ≥ 500 MB; skip PMTiles and emit GeoParquet-only > 2 GB (documented, never silent).
Derive PMTiles with tippecanoe -zg --drop-densest-as-needed.
Derive GeoParquet with duckdb — covering bbox STRUCT + ST_Hilbert order; verify a range read.
Track all three files with Git LFS, mint an Arc JWT, push to R2, prune, and build the absolute data.portaljs.com URLs.
Append one dual-tier datasets.json entry (pmtiles + geoparquet + original resources).
Verify: npx tsc --noEmit and a Range: 206 check on the R2 URL.
Report the tiers, manifest entry, and showcase route.

Output

Created: data/<slug>.pmtiles, data/<slug>.parquet, data/<slug>.<origext> (all LFS-tracked → R2); data/<slug>.4326.geojson (intermediate; can be pruned).
Modified: datasets.json (one dual-tier entry appended); .gitattributes (LFS tracking).
Verified: npx tsc --noEmit passes; the R2 URLs answer HTTP 206 range reads.
Result: /@<namespace>/<slug> renders the PMTiles map and the GeoParquet spatial-query panel together, with no page edits.

Error Handling

Symptom	Cause	Fix
`MISSING_TOOLS`	`ogr2ogr`/`tippecanoe`/`duckdb` (or duckdb `spatial`) absent	Print the per-OS install line and stop; re-run after installing.
`UNSUPPORTED_FORMAT`	Raster `.tif`/`.tiff` (COG tier, later phase)	Use `portaljs-add-dataset` for tabular; await the COG phase.
`SHAPEFILE_NOT_ZIPPED`	Bare `.shp` with no siblings	Zip the whole `.shp/.dbf/.shx/.prj` set and pass the `.zip`.
`MULTI_LAYER`	GPKG/KML with more than one layer	List layers and ask which to ingest; pass the layer name.
`REPROJECTION_FAILED`	`ogr2ogr` error, often a missing `.prj`	Show stderr; re-run with `-s_srs EPSG:<code>`.
`EMPTY_OUTPUT`	Normalized GeoJSON has 0 features	Check the geometry column / CRS of the source.
`TILING_FAILED` / `GEOPARQUET_FAILED`	tippecanoe or duckdb non-zero	Show stderr; for very large inputs see the size escape hatch.
`LFS_PUSH_FAILED`	Missing/expired Arc token or unset `lfs.url`	Re-mint the JWT (see `portaljs-deploy`); confirm `git config lfs.url`.

Examples

Example 1 — Ingest a GeoJSON into both tiers

/portaljs-add-geo source=./data/rivers.geojson name="World Rivers" namespace=reference

Example 2 — Zipped Shapefile from a URL

/portaljs-add-geo source=https://example.com/admin-boundaries.zip slug=admin-boundaries

Example 3 — GeoPackage with an explicit layer and namespace

/portaljs-add-geo source=./data/census.gpkg slug=census-tracts namespace=statistics

Resources

Full workflow: .claude/commands/portaljs-add-geo.md
Flags, thresholds, and the dual-tier manifest shape: references/reference.md
Related skills: portaljs-add-dataset, portaljs-add-map, portaljs-add-resource, portaljs-deploy
tippecanoe: https://github.com/felt/tippecanoe · DuckDB spatial: https://duckdb.org/docs/extensions/spatial

Frequently asked questions about PortalJS Add Geo

Similar skills

Single-Cell RNA-seq QC

Automate quality control for single-cell RNA-seq data.

Instrument Data to Allotrope Converter

Standardize lab data for seamless integration.

SQL Server Table Reconciliation

Efficiently compare SQL Server tables across instances.

Data Cleaning and Variable Screening

Streamline credit risk data preprocessing for modeling.

Arize Dataset

Manage and query Arize datasets efficiently.

Spreadsheet Management

Efficiently create, edit, and analyze spreadsheet files.