PortalJS — Add Resource
Overview
Add a resource — an additional file — to a dataset that already exists in a
portaljs-catalog portal. Where /portaljs-add-dataset creates a new dataset
(one file), this skill adds a file to an existing one: a data dictionary, a
methodology document, or another data file (e.g. a second year's figures).
Mirrors the Frictionless Data Package model: a dataset holds a resources[] array,
and the showcase at /@<namespace>/<slug> renders one section per resource (preview,
schema, download). A single-file dataset migrates to resources[] automatically the
first time a second file is added — no data is lost.
Prerequisites
- An existing PortalJS portal (
portaljs-catalog template) with datasets.json,
package.json, and pages/[owner]/[slug].tsx present.
- The target dataset already registered in
datasets.json.
- The new resource's source: a local file path or a public URL, in CSV, TSV, JSON
(array), or GeoJSON format.
- Node 18+ installed to run
npx next build for verification.
Instructions
The canonical, full step-by-step workflow lives in
.claude/commands/portaljs-add-resource.md
in this repository — that file is the single source of truth. Read and follow it. Summary:
- Gather input (interview if thin):
DATASET (slug or namespace/slug), SOURCE
(path or URL), PORTAL_DIR (default .), RESOURCE_NAME, RESOURCE_TITLE,
DESCRIPTION. If DATASET or SOURCE is missing, list datasets from
datasets.json and ask.
- Validate the portal and locate the dataset entry by slug (and namespace, if
given). If the dataset does not exist, offer
/portaljs-add-dataset instead.
- Detect the format from extension/Content-Type, fetch (check HTTP status) or
confirm the local path exists, then copy into
PORTAL_DIR/public/data/ under a
non-colliding filename.
- Update
datasets.json: if the dataset has no resources yet, migrate its
top-level file/format/schema into the first resource (lossless), then
append the new resource; if resources already exists, just append, keeping
name unique within the array.
- Verify the build with
npx next build, capturing output to a log file; fix
malformed JSON before reporting success.
- Report the outcome (see Output below).
Output
✓ Resource added to DATASET: RESOURCE_TITLE (RESOURCE_NAME.EXT)
- Data file: public/data/RESOURCE_NAME.EXT
- Manifest: datasets.json (dataset now has <n> resources)
- Showcase: /@<namespace>/<slug> renders a section per resource
If this was the first migration to multi-resource, note that the dataset's single
file was moved into resources[] with no data lost.
Error Handling
| Symptom |
Cause |
Fix |
| "Dataset not found" |
DATASET slug/namespace doesn't match any entry in datasets.json |
List datasets from datasets.json and ask the user to pick, or run /portaljs-add-dataset to create it |
npx next build fails with a JSON parse error |
Manually edited datasets.json has a trailing comma or unescaped character |
Re-open the file, fix the JSON, and rebuild before reporting success |
| Resource file fails to fetch (non-2xx) |
SOURCE URL is wrong, private, or the host is down |
Confirm the URL in a browser or with curl -I SOURCE; ask for a corrected URL or a local path |
New resource's filename collides with an existing one in /public/data |
Auto-derived RESOURCE_NAME matches an existing file stem |
Pick a distinct RESOURCE_NAME, or let the skill append a numeric suffix |
| Showcase doesn't render the new section after build |
name in the new resource object duplicates an existing resource's name |
Rename the resource's name to something unique within that dataset's resources[] |
Examples
Example 1 — Add a data dictionary to a single-file dataset
/portaljs-add-resource orders ./data/orders-data-dictionary.csv --title "Data dictionary"
orders was a single CSV. It is migrated to a two-resource dataset (the original
data plus the dictionary), and its showcase now renders a section for each.
Example 2 — Add a resource by URL to a dataset that already has resources
/portaljs-add-resource climate-observations https://example.org/data/methodology.json --name methodology --title "Methodology notes"
The skill fetches the URL, checks the HTTP status, copies it to
public/data/methodology.json, and appends it to the existing resources[] array.
Example 3 — Run with no arguments (interview mode)
/portaljs-add-resource
With no arguments, the skill lists datasets from datasets.json, asks which one to
extend and for the new file's path or URL, then proceeds through steps 2-6 above.
Resources
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/community/portaljs/skills/portaljs-add-resource/SKILL.md
1---2name: portaljs-add-resource3description: "Add another file (resource) to an EXISTING dataset in a PortalJS portal — a data dictionary, methodology, or an additional data file. Turns a single-file dataset into a multi-resource one; the showcase renders a section per resource. Use when a dataset needs a second file, such as a data dictionary, methodology doc, or an additional period's data."4allowed-tools: "Read, Write, Edit, Bash(npm:*), Bash(curl:*), Bash(mkdir:*), Bash(cp:*), WebFetch"5category: data-science-and-ml6source_repo: jeremylongshore/claude-code-plugins-plus-skills7source_path: "plugins/community/portaljs/skills/portaljs-add-resource/SKILL.md"8source_url: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/community/portaljs/skills/portaljs-add-resource/SKILL.md9---101112# PortalJS — Add Resource1314## Overview1516Add a resource — an additional file — to a dataset that already exists in a17`portaljs-catalog` portal. Where `/portaljs-add-dataset` creates a **new** dataset18(one file), this skill adds a file to an **existing** one: a data dictionary, a19methodology document, or another data file (e.g. a second year's figures).2021Mirrors the Frictionless Data Package model: a dataset holds a `resources[]` array,22and the showcase at `/@<namespace>/<slug>` renders one section per resource (preview,23schema, download). A single-file dataset migrates to `resources[]` automatically the24first time a second file is added — no data is lost.2526## Prerequisites2728- An existing PortalJS portal (`portaljs-catalog` template) with `datasets.json`,29 `package.json`, and `pages/[owner]/[slug].tsx` present.30- The target dataset already registered in `datasets.json`.31- The new resource's source: a local file path or a public URL, in CSV, TSV, JSON32 (array), or GeoJSON format.33- Node 18+ installed to run `npx next build` for verification.3435## Instructions3637The canonical, full step-by-step workflow lives in38[`.claude/commands/portaljs-add-resource.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-resource.md)39in this repository — that file is the single source of truth. Read and follow it. Summary:40411. Gather input (interview if thin): `DATASET` (slug or `namespace/slug`), `SOURCE`42 (path or URL), `PORTAL_DIR` (default `.`), `RESOURCE_NAME`, `RESOURCE_TITLE`,43 `DESCRIPTION`. If `DATASET` or `SOURCE` is missing, list datasets from44 `datasets.json` and ask.452. Validate the portal and locate the dataset entry by slug (and namespace, if46 given). If the dataset does not exist, offer `/portaljs-add-dataset` instead.473. Detect the format from extension/Content-Type, fetch (check HTTP status) or48 confirm the local path exists, then copy into `PORTAL_DIR/public/data/` under a49 non-colliding filename.504. Update `datasets.json`: if the dataset has no `resources` yet, migrate its51 top-level `file`/`format`/`schema` into the first resource (lossless), then52 append the new resource; if `resources` already exists, just append, keeping53 `name` unique within the array.545. Verify the build with `npx next build`, capturing output to a log file; fix55 malformed JSON before reporting success.566. Report the outcome (see Output below).5758## Output5960```61✓ Resource added to DATASET: RESOURCE_TITLE (RESOURCE_NAME.EXT)62 - Data file: public/data/RESOURCE_NAME.EXT63 - Manifest: datasets.json (dataset now has <n> resources)64 - Showcase: /@<namespace>/<slug> renders a section per resource65```6667If this was the first migration to multi-resource, note that the dataset's single68`file` was moved into `resources[]` with no data lost.6970## Error Handling7172| Symptom | Cause | Fix |73|---|---|---|74| "Dataset not found" | `DATASET` slug/namespace doesn't match any entry in `datasets.json` | List datasets from `datasets.json` and ask the user to pick, or run `/portaljs-add-dataset` to create it |75| `npx next build` fails with a JSON parse error | Manually edited `datasets.json` has a trailing comma or unescaped character | Re-open the file, fix the JSON, and rebuild before reporting success |76| Resource file fails to fetch (non-2xx) | `SOURCE` URL is wrong, private, or the host is down | Confirm the URL in a browser or with `curl -I SOURCE`; ask for a corrected URL or a local path |77| New resource's filename collides with an existing one in `/public/data` | Auto-derived `RESOURCE_NAME` matches an existing file stem | Pick a distinct `RESOURCE_NAME`, or let the skill append a numeric suffix |78| Showcase doesn't render the new section after build | `name` in the new resource object duplicates an existing resource's `name` | Rename the resource's `name` to something unique within that dataset's `resources[]` |7980## Examples8182### Example 1 — Add a data dictionary to a single-file dataset8384```85/portaljs-add-resource orders ./data/orders-data-dictionary.csv --title "Data dictionary"86```87`orders` was a single CSV. It is migrated to a two-resource dataset (the original88data plus the dictionary), and its showcase now renders a section for each.8990### Example 2 — Add a resource by URL to a dataset that already has resources9192```93/portaljs-add-resource climate-observations https://example.org/data/methodology.json --name methodology --title "Methodology notes"94```95The skill fetches the URL, checks the HTTP status, copies it to96`public/data/methodology.json`, and appends it to the existing `resources[]` array.9798### Example 3 — Run with no arguments (interview mode)99100```101/portaljs-add-resource102```103With no arguments, the skill lists datasets from `datasets.json`, asks which one to104extend and for the new file's path or URL, then proceeds through steps 2-6 above.105106## Resources107108- [`.claude/commands/portaljs-add-resource.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-resource.md) — canonical workflow this skill follows109- [`references/reference.md`](references/reference.md) — resource entry fields, single-to-multi-resource layout, troubleshooting110- Related skills: `/portaljs-add-dataset` (create a new dataset), `/portaljs-define-schema` (describe a resource's fields)111- [Frictionless Data — Data Package resources](https://datapackage.org/standard/data-resource/) — the data model this feature mirrors112113---114115**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `plugins/community/portaljs/skills/portaljs-add-resource/SKILL.md`
jeremylongshore