SkillAgentSearch skills...

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/portaljs

Installs into whichever agent you are using.

About this skill
⚡

Claude Commands

Claude Code slash commands

Quality Score

94/100

Supported Platforms

Claude Code

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.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
14/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
portaljs-add-geo (this skill)by datopian942.4k2mo agoClaude Commands
claude-memby thedotmack100117.6ktodayCLAUDE.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
Understand-Anythingby Egonex-AI10092.8k1d agoCLAUDE.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.

description: 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 bbox column, 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, .csv with 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 URL
  • PORTAL_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 description
  • NAMESPACE — namespace value (default: read the first existing entry's namespace from datasets.json, else reference)

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 -so feature 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"
  • -zg auto-picks max zoom from feature density; --drop-densest-as-needed keeps 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

View on GitHub
GitHub Stars2.4k
CategoryData
Updated2mo ago
Forks335

Languages

TypeScript

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions