portaljs-add-geo
Auto-ingest a geospatial file (GeoJSON, Shapefile, GeoPackage, KML/KMZ, FlatGeobuf, CSV-with-geometry) into a PortalJS portal — on your own machine, no server.
Install / Use
npx skills add datopian/portaljsInstalls into whichever agent you are using.
Claude Commands
Claude Code slash commands
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of portaljs-add-geo
portaljs-add-geo scores 94/100 on our quality scale, 102nd of 604 Data & Analytics skills we index (top 17%).
Its Claude Commands is 21 KB long, well organised into 25 sections with 20 code examples: a thorough specification that gives an agent plenty to work with.
With 2,356 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so portaljs-add-geo is actively maintained.
- Our last check on 2026-11-16 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
portaljs-add-geo compared with similar skills
All 4 of these similar skills score higher than portaljs-add-geo; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| portaljs-add-geo (this skill)by datopian | 94 | 2.4k | 2mo ago | Claude Commands |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
Frequently asked questions
- How do I install portaljs-add-geo?
- Run
npx skills add datopian/portaljs. The install tabs above show the steps for each supported agent. - Which AI agents does portaljs-add-geo work with?
- It is written for Claude Code, as a Claude Commands file. Other agents that read the same format can often use it too.
- Is portaljs-add-geo safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is portaljs-add-geo still maintained?
- The repository was last updated about 2 months ago, so portaljs-add-geo is actively maintained.
Skill content
View source on GitHubdescription: Auto-ingest a geospatial file (GeoJSON, Shapefile, GeoPackage, KML/KMZ, FlatGeobuf, CSV-with-geometry) into a PortalJS portal — on your own machine, no server. Normalizes CRS to EPSG:4326, derives a PMTiles render tier + a GeoParquet query tier, pushes all three to R2 via Git LFS, and emits one dual-tier datasets.json entry the showcase renders with <MapPreview> + <GeoQuery>. allowed-tools: Read, Write, Edit, Bash, WebFetch
/portaljs-add-geo
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 file this produces two derivatives plus the preserved original:
- PMTiles — the render tier. A single vector-tile archive
<MapPreview>renders with MapLibre GL over HTTP range requests: any dataset size pans/zooms with no tile server. - GeoParquet — the query tier. A GeoParquet 1.1 file (covering
bboxcolumn, Hilbert-sorted)<GeoQuery>runs spatial SQL over in place via DuckDB-Wasm. - Original — the untouched upload in its native CRS, kept downloadable as the source artifact.
All three land on Cloudflare R2 (via Git LFS → Giftless), and the skill appends one
datasets.json entry whose resources[] are exactly the shape the showcase auto-renders
(PR #1647 / the @reference/world-boundaries demo): a pmtiles resource → <MapPreview>,
a geoparquet resource → <GeoQuery>, and the original as a download. No page edits — the
dynamic showcase route pages/[owner]/[slug].tsx renders each resource by its format.
This automates the manual tippecanoe / duckdb recipes documented in the template README
(the interim ingest path). Use it whenever the source is a vector geo format; for plain
tabular data use /portaljs-add-dataset, and for a Leaflet view over small GeoJSON use
/portaljs-add-map.
Runtime — native shell-out, detect-or-instruct
This runs native CLIs on the user's machine (locked direction, 2026-07-08 — overrides po-6sr §7's server-compute sketch). No container, no cloud job. tippecanoe has no mature WASM build, so the PMTiles tier fundamentally needs the native binary; skills already shell out to git-lfs and npm, so native geo deps fit the model. Three tools:
| Tool | Role | Why this tool |
|------|------|---------------|
| GDAL (ogr2ogr, ogrinfo) | Read every vector input; reproject → EPSG:4326; emit the normalized GeoJSON intermediate | Widest driver set (SHP, GPKG, KML/KMZ, FGB, CSV-geom) |
| tippecanoe | normalized GeoJSON → PMTiles (render tier) | The de-facto tiler; no WASM equivalent |
| duckdb (+ spatial) | normalized GeoJSON → GeoParquet 1.1 with covering bbox + Hilbert sort (query tier) | The proven writer — PR #1647 verified <GeoQuery> against duckdb output; ogr2ogr's Parquet driver won't cleanly emit the covering-bbox column + Hilbert ordering the bbox-first query needs to prune |
Required input — ask, don't error
- Source — a local geo file path or a public URL. Supported:
.geojson/.json(GeoJSON),.zip(zipped Shapefile),.gpkg,.kml/.kmz,.fgb,.csvwith a geometry/lat-lon column. Raster (.tif/.tiff) is out of scope (COG is a later phase). - Portal directory — path to the portal project (defaults to current directory).
- Namespace — the dataset's namespace value (subject for
'theme'portals, publisher for'owner'portals).
If the source is missing, ask for it — never dead-end. The user can say "use defaults".
Steps
1. Gather input from $ARGUMENTS (interview if thin)
Extract:
SOURCE— geo file path or URLPORTAL_DIR— portal directory (default:.)DATASET_NAME— human name (default: derived from filename)DATASET_SLUG— URL slug (default: lowercase hyphenated filename without extension)DESCRIPTION— optional one-line descriptionNAMESPACE— namespace value (default: read the first existing entry'snamespacefromdatasets.json, elsereference)
If SOURCE is missing, ask (one focused prompt) and wait:
To add a geospatial dataset I need:
1. Source: a local geo file path or public URL (required) —
GeoJSON, zipped Shapefile (.zip), GeoPackage (.gpkg), KML/KMZ, FlatGeobuf (.fgb),
or a CSV with a geometry/lat-lon column.
2. Portal directory (Enter for current directory)
3. Dataset name (Enter to use the filename)
4. Namespace value — the group this dataset belongs to
(subject if the portal is "theme" mode, publisher if "owner" mode; Enter to reuse the catalog's existing namespace)
Read NAMESPACE_TYPE from PORTAL_DIR/lib/datasets.ts so you can phrase the namespace
question correctly ("subject" vs "publisher").
2. Check the native tools (detect-or-instruct — hard gate)
Do this before touching data. Missing tools stop the run with a one-line install — never silently skip a tier.
MISSING=""
for t in ogr2ogr tippecanoe duckdb; do
command -v "$t" >/dev/null 2>&1 || MISSING="$MISSING $t"
done
If MISSING is non-empty, print the install for the user's OS and STOP:
ERROR: [add-geo] MISSING_TOOLS Missing:<MISSING>. Install then re-run:
macOS: brew install gdal tippecanoe duckdb
Debian/Ubuntu: sudo apt-get install -y gdal-bin duckdb # tippecanoe: apt where available,
else build from source — https://github.com/felt/tippecanoe
Windows: not supported natively — use WSL (Ubuntu) and follow the Debian steps.
Detect Windows-native ($OSTYPE = msys/win32, or uname shows MINGW/MSYS) and print the
WSL note prominently — this is a documented first-cut limitation, not a bug.
Verify the duckdb spatial extension can load (it auto-installs on first use, needs network
once): duckdb -c "INSTALL spatial; LOAD spatial; SELECT 1;" — if this fails, report it as
MISSING_TOOLS (duckdb spatial) with the same stop behavior.
3. Validate the portal directory
Confirm PORTAL_DIR/datasets.json, PORTAL_DIR/package.json, and
PORTAL_DIR/pages/[owner]/[slug].tsx exist. If datasets.json is missing, tell the user
this isn't the portaljs-catalog template (it may be an older single-page template) and ask
how to proceed rather than failing silently.
Confirm the template renders the geo tiers: components/MapPreview.tsx and
components/GeoQuery.tsx should exist (they shipped in PR #1647). If they don't, the portal
predates the dual-tier showcase — tell the user to update the template first.
4. Fetch (if URL) and detect the input format
If SOURCE is a URL: download it to a temp path (geo derivatives are computed locally, so
unlike /portaljs-add-dataset there is no passthrough option here):
curl -fL "$SOURCE" -o "/tmp/$DATASET_SLUG.$EXT"
If the fetch fails, report the HTTP status and ask the user to confirm the URL is public.
If SOURCE is a local path: check it exists; if not, report and ask for a correct path.
Detect the format from extension + content:
| Input | Detect on | ogr2ogr source spec |
|-------|-----------|---------------------|
| GeoJSON | .geojson, or .json whose parsed type is FeatureCollection/Feature/a geometry | the file path |
| Zipped Shapefile | .zip containing .shp + .dbf + .shx (+ .prj for CRS) | /vsizip/<abs-path>.zip |
| GeoPackage | .gpkg | the file path (multi-layer → Step 5a) |
| KML / KMZ | .kml, .kmz | the file path (GDAL LIBKML driver reads KMZ directly) |
| FlatGeobuf | .fgb | the file path |
| CSV + geometry | .csv with a WKT geometry column or lat/lon columns | see Step 5 CSV note |
| Raster | .tif, .tiff | UNSUPPORTED — stop (see below) |
Guards:
- Raster →
ERROR: [add-geo] UNSUPPORTED_FORMAT Raster .tif/.tiff (COG tier) is out of scope. Use /portaljs-add-dataset for tabular data, or wait for the COG phase. - Bare
.shp(not zipped) →ERROR: [add-geo] SHAPEFILE_NOT_ZIPPED A shapefile is multi-file (.shp/.dbf/.shx/.prj). Zip the whole set and pass the .zip. - Plain CSV with no geometry → suggest
/portaljs-add-dataset(tabular path).
5. Preserve the original + normalize CRS → EPSG:4326
Work in a scratch dir; keep the original untouched as artifact #1.
cd PORTAL_DIR && mkdir -p data
SRC="<the source spec from Step 4>" # file path, /vsizip/..., etc.
# Report the source CRS (for the record; also catches missing .prj early):
ogrinfo -so -al "$SRC" | grep -iE "EPSG|GEOGCS|PROJCS" | head -3
# Normalize to EPSG:4326 RFC7946 GeoJSON (the intermediate both tools ingest):
ogr2ogr -f GeoJSON -t_srs EPSG:4326 -lco RFC7946=YES \
"data/$DATASET_SLUG.4326.geojson" "$SRC"
5a. Multi-layer sources (GPKG/KML). If ogrinfo lists more than one layer, list them and
ask which to ingest (or accept a layer name), then add it as the last ogr2ogr arg:
ogr2ogr ... "data/$DATASET_SLUG.4326.geojson" "$SRC" "<layer-name>".
ERROR: [add-geo] MULTI_LAYER if you must stop for the choice.
5b. CSV with geometry. Point ogr2ogr at the geometry columns via open options:
# WKT geometry column named e.g. "geom":
ogr2ogr -f GeoJSON -t_srs EPSG:4326 -oo GEOM_POSSIBLE_NAMES=geom -oo KEEP_GEOM_COLUMNS=NO \
"data/$DATASET_SLUG.4326.geojson" "$SRC"
# or lat/lon columns:
ogr2ogr -f GeoJSON -t_srs EPSG:4326 -oo X_POSSIBLE_NAMES=lon,lng,longitude \
-oo Y_POSSIBLE_NAMES=lat,latitude -oo KEEP_GEOM_COLUMNS=NO \
"data/$DATASET_SLUG.4326.geojson" "$SRC"
Guards:
- ogr2ogr non-zero →
ERROR: [add-geo] REPROJECTION_FAILED <stderr>. If the source CRS is unknown (missing .prj), re-run adding -s_srs EPSG:<code>. - Zero features in the output (
ogrinfo -sofeature count is 0) →ERROR: [add-geo] EMPTY_OUTPUT Normalized GeoJSON has no features — check the geometry column / CRS.
Then also copy the original into the repo under its native extension for the download
resource: cp "<original source file>" "data/$DATASET_SLUG.<origext>" (for a URL source, the
/tmp download; for a zipped shapefile, keep the .zip).
6. Size escape hatch (measure the normalized GeoJSON — what both tools ingest)
Threshold on the normalized GeoJSON bytes (format-independent; it's exactly what tippecanoe and duckdb read) with feature count as a secondary signal. These are heuristics for an ~8–16 GB laptop — document them as tunable, not hard limits.
BYTES=$(wc -c < "data/$DATASET_SLUG.4326.geojson")
- < 500 MB → proceed normally (both tiers).
- 500 MB – 2 GB (or ≥ ~5M features) → soft warn: "This is large; local tiling + Parquet may take several minutes and multiple GB of RAM." Proceed.
- > 2 GB → skip PMTiles, emit GeoParquet-only (duckdb streams row groups and
stays practical where tippecanoe's memory/time do not). Print exactly what was skipped and
the two ways to still get a render tier — no silent truncation:
⚠ PMTiles skipped: normalized GeoJSON is <BYTES> (> 2 GB). The query tier (GeoParquet) is included. To add the render tier later, either: (a) keep it query-only (GeoQuery works without PMTiles), or (b) run `tippecanoe -zg --drop-densest-as-needed -o out.pmtiles in.geojson` on a bigger machine, then attach it with /portaljs-add-resource (format: pmtiles).
This documented degradation is the ONE place the original "needs big compute" concern lives — as a warning + manual fallback, never a container dependency.
7. Derive the PMTiles render tier (unless skipped in Step 6)
tippecanoe -zg --drop-densest-as-needed --extend-zooms-if-still-dropping --force \
-o "data/$DATASET_SLUG.pmtiles" "data/$DATASET_SLUG.4326.geojson"
-zgauto-picks max zoom from feature density;--drop-densest-as-neededkeeps tiles under the size limit for dense data; attributes are preserved by default (click-to-inspect).- Small reference layers (e.g. country boundaries) can instead cap zoom:
-z5. Prefer
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
