portaljs-add-dataset

Add a dataset (CSV, TSV, JSON, or GeoJSON) to an existing PortalJS portal. Appends an entry to datasets.json so the catalog and showcase render it automatically; routes the data by source (local file vs remote URL) — R2 via Git LFS by default, remote URLs by passthrough. Use when registering a new dataset in a scaffolded portal.

v1.0.0
Datopian
MIT

Allowed Tools

ReadWriteEditBash(npm:*)Bash(npx:*)Bash(git:*)Bash(curl:*)Bash(mkdir:*)Bash(cp:*)WebFetch

Provided by Plugin

portaljs

Agentic skills for building PortalJS data portals — recommend an architecture, scaffold a portal, add datasets, charts, and maps, connect a CKAN backend, deploy, and audit data quality.

community v0.1.0
View Plugin

Installation

This skill is included in the portaljs plugin:

/plugin install portaljs@claude-code-plugins-plus

Click to copy

Instructions

PortalJS — Add Dataset

Overview

Register a dataset in a PortalJS (portaljs-catalog) portal. The skill appends one entry to

datasets.json — the single source of truth for the catalog — and routes the underlying

bytes by source first, then size: a local file defaults to R2 via Git LFS, a remote URL

defaults to passthrough (no copy). No per-dataset page is created; the catalog at /search

lists the new entry and the dynamic showcase route pages/[owner]/[slug].tsx renders it

automatically at /@/. Supported formats for the showcase preview: CSV,

TSV, JSON (array), and GeoJSON.

Prerequisites

  • A scaffolded PortalJS portal (see portaljs-new-portal) with datasets.json,

package.json, and pages/[owner]/[slug].tsx present.

  • The source data: a local file path or a publicly reachable URL.
  • For the R2/Git LFS default route: git and git-lfs installed, and an Arc account token

(or an OSS Giftless key) to mint a push-scoped LFS credential.

  • Node 18+ and npm available in the portal directory.

Instructions

The canonical, full step-by-step workflow is

.claude/commands/portaljs-add-dataset.md —

the single source of truth. Read and follow it when executing. Summary:

  1. Gather input from $ARGUMENTS — source (file path or URL), portal directory (default

.), dataset name/slug, description, namespace. If the source is missing, interview the

user; never dead-end.

  1. Validate the portal directory: confirm datasets.json, package.json, and

pages/[owner]/[slug].tsx exist.

  1. Detect the format from the file extension, URL extension, or Content-Type header

(CSV, TSV, JSON array, or GeoJSON); reject anything else and ask for a conversion.

  1. Route the data by source: remote URL → passthrough (default) or adopt into R2 (opt-in);

local file → R2 via Git LFS (default) or inline into public/data/ (fenced exception for

bundled samples or an OSS-no-R2 fallback).

  1. Append one entry to datasets.json — slug, namespace, name, description, file

(the routed path/URL), format — keeping (namespace, slug) unique.

  1. Verify the build with npx next build; fix errors (commonly malformed JSON) before

reporting success.

  1. Report the route taken, the manifest change, and the showcase URL.

Output

  • Modified: datasets.json (one entry appended).
  • Created (route-dependent): data/. tracked via Git LFS (R2 default), or

public/data/. (inline exception). Nothing is created for remote passthrough.

  • Verified: npx next build passes.
  • Result: the dataset appears in /search and renders at /@/.

Error Handling

Symptom Cause Fix
Fetch fails for a URL source Non-200 status or unreachable host Report the HTTP status and ask the user to confirm the URL is publicly accessible.
"Not a portaljs-catalog portal" datasets.json missing This is an older single-page template; ask the user how to proceed rather than failing silently.
Unsupported format Extension/content-type isn't csv/tsv/json/geojson Ask the user to convert the source before continuing.
git lfs push has nothing to stream git lfs install --local never ran, so raw bytes were committed instead of a pointer Run git lfs install --local before git lfs track, re-add and re-commit the file.
R2 PUT returns 400 A broad http.extraHeader was set and replayed onto the presigned URL Use the _jwt Basic-auth piggyback in lfs.url only — never a global http.extraHeader.
(namespace, slug) clash Another entry already uses that pair Ask the user for a different slug or namespace.
next build fails Malformed JSON in datasets.json Print the build log, fix the JSON, rebuild before reporting success.

Examples

Example 1 — Local CSV, default R2 route


/portaljs-add-dataset ./data/co2-emissions.csv namespace=climate

Moves the file into data/, tracks it with Git LFS, pushes it to R2, and appends a manifest

entry whose file is the resulting https://data.portaljs.com/... URL.

Example 2 — Remote URL, passthrough (no download)


/portaljs-add-dataset https://example.org/open-data/trade.csv namespace=trade

Detects the format from the response headers and records the URL as-is in datasets.json —

no bytes are copied.

Example 3 — GeoJSON adopted into R2


/portaljs-add-dataset https://example.org/boundaries.geojson namespace=reference adopt=true

Downloads the file, then routes it as a local file through the Git LFS → R2 path so it is

hosted and versioned under the portal (useful when in-browser range queries are needed).

Example 4 — Bundled sample data, inline exception


/portaljs-add-dataset ./samples/demo.csv namespace=reference

When the portal has no R2 credentials (OSS self-host) or the file is bundled sample data,

the skill copies it into public/data/ instead, per the .gitattributes inline fence.

Resources

Ready to use portaljs?

Related Skills

agent-patterns

'Execute this skill should be used when the user asks about "SPAWN REQUEST.

Read

anti-deception

Use BEFORE responding when the user's request shows pressure to validate or agree ("tell them what they want", "make them happy", "convince them"), manufactured urgency (artificial deadline), authority appeals (citing investors, advisors, lawyers, experts), demands to certify without evidence, requests to soften an honest assessment, "help me convince X of Y" or "how do I get X to agree" framings where Y is dubious, asking you to commit to numbers beyond data, framing a wrong assumption as fact, or any setup where the obvious helpful answer would compromise honesty.

mcp__ejentum__anti-deception

api-contract

'Configure this skill should be used when the user asks about "API contract",.

Read

arcgis-to-portaljs

Migrate a whole ArcGIS Hub site into a PortalJS Arc portal end-to-end.

ReadWriteEdit

boycott-filter

"Personal boycott list \u2014 users can conversationally tell the agent\.

Bash(curl:*)

claude-reflect

'Execute self-learning system that captures corrections during sessions.

ReadWriteEdit