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.4---567# PortalJS — Add Resource89## Overview1011Add a resource — an additional file — to a dataset that already exists in a12`portaljs-catalog` portal. Where `/portaljs-add-dataset` creates a **new** dataset13(one file), this skill adds a file to an **existing** one: a data dictionary, a14methodology document, or another data file (e.g. a second year's figures).1516Mirrors the Frictionless Data Package model: a dataset holds a `resources[]` array,17and the showcase at `/@<namespace>/<slug>` renders one section per resource (preview,18schema, download). A single-file dataset migrates to `resources[]` automatically the19first time a second file is added — no data is lost.2021## Prerequisites2223- An existing PortalJS portal (`portaljs-catalog` template) with `datasets.json`,24 `package.json`, and `pages/[owner]/[slug].tsx` present.25- The target dataset already registered in `datasets.json`.26- The new resource's source: a local file path or a public URL, in CSV, TSV, JSON27 (array), or GeoJSON format.28- Node 18+ installed to run `npx next build` for verification.2930## Instructions3132The canonical, full step-by-step workflow lives in33[`.claude/commands/portaljs-add-resource.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-resource.md)34in this repository — that file is the single source of truth. Read and follow it. Summary:35361. Gather input (interview if thin): `DATASET` (slug or `namespace/slug`), `SOURCE`37 (path or URL), `PORTAL_DIR` (default `.`), `RESOURCE_NAME`, `RESOURCE_TITLE`,38 `DESCRIPTION`. If `DATASET` or `SOURCE` is missing, list datasets from39 `datasets.json` and ask.402. Validate the portal and locate the dataset entry by slug (and namespace, if41 given). If the dataset does not exist, offer `/portaljs-add-dataset` instead.423. Detect the format from extension/Content-Type, fetch (check HTTP status) or43 confirm the local path exists, then copy into `PORTAL_DIR/public/data/` under a44 non-colliding filename.454. Update `datasets.json`: if the dataset has no `resources` yet, migrate its46 top-level `file`/`format`/`schema` into the first resource (lossless), then47 append the new resource; if `resources` already exists, just append, keeping48 `name` unique within the array.495. Verify the build with `npx next build`, capturing output to a log file; fix50 malformed JSON before reporting success.516. Report the outcome (see Output below).5253## Output5455```56✓ Resource added to DATASET: RESOURCE_TITLE (RESOURCE_NAME.EXT)57 - Data file: public/data/RESOURCE_NAME.EXT58 - Manifest: datasets.json (dataset now has <n> resources)59 - Showcase: /@<namespace>/<slug> renders a section per resource60```6162If this was the first migration to multi-resource, note that the dataset's single63`file` was moved into `resources[]` with no data lost.6465## Error Handling6667| Symptom | Cause | Fix |68|---|---|---|69| "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 |70| `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 |71| 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 |72| 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 |73| 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[]` |7475## Examples7677### Example 1 — Add a data dictionary to a single-file dataset7879```80/portaljs-add-resource orders ./data/orders-data-dictionary.csv --title "Data dictionary"81```82`orders` was a single CSV. It is migrated to a two-resource dataset (the original83data plus the dictionary), and its showcase now renders a section for each.8485### Example 2 — Add a resource by URL to a dataset that already has resources8687```88/portaljs-add-resource climate-observations https://example.org/data/methodology.json --name methodology --title "Methodology notes"89```90The skill fetches the URL, checks the HTTP status, copies it to91`public/data/methodology.json`, and appends it to the existing `resources[]` array.9293### Example 3 — Run with no arguments (interview mode)9495```96/portaljs-add-resource97```98With no arguments, the skill lists datasets from `datasets.json`, asks which one to99extend and for the new file's path or URL, then proceeds through steps 2-6 above.100101## Resources102103- [`.claude/commands/portaljs-add-resource.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-resource.md) — canonical workflow this skill follows104- [`references/reference.md`](references/reference.md) — resource entry fields, single-to-multi-resource layout, troubleshooting105- Related skills: `/portaljs-add-dataset` (create a new dataset), `/portaljs-define-schema` (describe a resource's fields)106- [Frictionless Data — Data Package resources](https://datapackage.org/standard/data-resource/) — the data model this feature mirrors107108---109110**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