agentleFS
Sign inStart free
datopiandatopian/portaljs/skills/portaljs-add-geo/SKILL.md

portaljs-add-geo

Skill2.4k starsChanged 12 days agoMITView on GitHub

Auto-ingest a geospatial file (GeoJSON, Shapefile, GeoPackage, KML/KMZ, FlatGeobuf, CSV-with-geometry) into a PortalJS portal on the user's own machine, with no server. Normalizes CRS to EPSG:4326, derives a PMTiles render tier and a GeoParquet query tier, pushes all three artifacts to Cloudflare R2 via Git LFS, and appends one dual-tier datasets.json entry the showcase auto-renders. Use when the source is a vector geo format that needs a map or spatial-query view.

  • Installs packages

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All three land on Cloudflare R2 (Git LFS → Giftless), and the skill appends one datasets.json entry whose resources[] match the shape the …

    line 32
  2. Very specific:

    Verify: npx tsc --noEmit and a Range: 206 check on the R2 URL.

    line 70

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

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

SymptomCauseFix
MISSING_TOOLSogr2ogr/tippecanoe/duckdb (or duckdb spatial) absentPrint the per-OS install line and stop; re-run after installing.
UNSUPPORTED_FORMATRaster .tif/.tiff (COG tier, later phase)Use portaljs-add-dataset for tabular; await the COG phase.
SHAPEFILE_NOT_ZIPPEDBare .shp with no siblingsZip the whole .shp/.dbf/.shx/.prj set and pass the .zip.
MULTI_LAYERGPKG/KML with more than one layerList layers and ask which to ingest; pass the layer name.
REPROJECTION_FAILEDogr2ogr error, often a missing .prjShow stderr; re-run with -s_srs EPSG:<code>.
EMPTY_OUTPUTNormalized GeoJSON has 0 featuresCheck the geometry column / CRS of the source.
TILING_FAILED / GEOPARQUET_FAILEDtippecanoe or duckdb non-zeroShow stderr; for very large inputs see the size escape hatch.
LFS_PUSH_FAILEDMissing/expired Arc token or unset lfs.urlRe-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

Download now (ZIP)

Trending

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Aug 30: 0 new projectsWeek of Sep 6: 0 new projectsWeek of Sep 13: 0 new projectsWeek of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projects
Aug 2026Sep 2026Oct 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Who's talking about datopian/portaljs

The biggest 5 of 38 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 38

Talked about on GitHub and Hacker News (38 times).

On GitHub · 37

32 more on GitHub

On Hacker News · 1

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

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.

Check your setup, free