SkillAgentSearch skills...

portaljs-new-portal

Scaffold a new PortalJS data portal from a brief. Copies the canonical template from examples/portaljs-catalog and substitutes project tokens.

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

Tags

Our assessment of portaljs-new-portal

portaljs-new-portal scores 94/100 on our quality scale, 519th of 4,700 Development & Engineering skills we index (top 12%).

Its Claude Commands is 14 KB long, well organised into 25 sections with 15 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-new-portal 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-29. 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-new-portal compared with similar skills

All 4 of these similar skills score higher than portaljs-new-portal; compare them before choosing.

SkillScoreStarsUpdatedFormat
portaljs-new-portal (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-new-portal?
Run npx skills add datopian/portaljs. The install tabs above show the steps for each supported agent.
Which AI agents does portaljs-new-portal 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-new-portal 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-new-portal still maintained?
The repository was last updated about 2 months ago, so portaljs-new-portal is actively maintained.

description: Scaffold a new PortalJS data portal from a brief. Copies the canonical template from examples/portaljs-catalog and substitutes project tokens. allowed-tools: Read, Write, Edit, Bash

/portaljs-new-portal

Scaffold a production-ready PortalJS data portal. The skill is interactive: if the brief is thin, it interviews the user in three short rounds (mapped to the template's three surfaces — Home, Catalog, Showcase), echoes a brief back for confirmation, then copies examples/portaljs-catalog, substitutes placeholder tokens, sets the namespace mode, seeds any datasets, installs dependencies, and verifies the build.

The template you are scaffolding

examples/portaljs-catalog is the canonical template. It has three surfaces:

| Surface | Route | File | What it is | |---|---|---|---| | Home | / | pages/index.tsx | Search-first landing: hero + search box + suggested-query chips (__PROJECT_NAME__ / __DESCRIPTION__ tokens) | | Catalog / search | /search | pages/search.tsx | Client-side full-text list over datasets.json | | Dataset showcase | /@<namespace>/<slug> | pages/[owner]/[slug].tsx | One dataset: metadata, Table data preview, Download & API, and a Views placeholder for charts/maps |

The catalog is driven by datasets.json (the single source of truth) — each entry is { slug, name, description, file, format, namespace }. lib/datasets.ts exposes getDatasets(), getDataset(slug), getDatasetByNamespace(ns, slug), datasetHref(d) → /@${namespace}/${slug}, and a NAMESPACE_TYPE: 'theme' | 'owner' constant.

A portal uses exactly one namespace mode:

  • 'theme' — a single-publisher portal whose datasets are grouped by subject (e.g. @reference/country-codes). The showcase labels the namespace "Theme".
  • 'owner' — a multi-publisher portal whose datasets are grouped by who published them (e.g. @worldbank/country-codes). The showcase labels the namespace "Owner".

Search is a static client-side list for now. A live backend (e.g. CKAN, via /portaljs-connect-ckan) can replace datasets.json later without changing the URL structure.

Required input — interview, don't error

You need a project name and one-line description. Datasets are optional at scaffold time. Never dead-end with a missing-input error. If $ARGUMENTS is empty or thin, run the structured interview in Step 1 to gather what's missing. The user can say "use defaults" at any point to skip a round and accept the defaults below.

Steps

1. Interview the user (skip rounds already answered by $ARGUMENTS)

Parse $ARGUMENTS first and pre-fill anything it already specifies. Then ask only for what's still missing, one focused round at a time (wait for the answer before the next round). Each round maps to a template surface. Tell the user they can reply "use defaults" to take the defaults.

Round 1 — Home / basics:

Round 1 of 3 — the home page.
1. What's the portal called? (e.g. "Auckland Open Data Portal")
2. One-line description for the hero? (default: "An open data portal.")
3. Who is it for / what's it about? (helps pick suggested-search chips)

Round 2 — Catalog & discovery:

Round 2 of 3 — the catalog (the /search list).
1. Which datasets should it start with? Give file paths or URLs, or "none yet".
2. Roughly how many datasets total — a handful, dozens, hundreds?
3. Single publisher or multiple?
   - single  → datasets grouped by SUBJECT (namespace mode "theme")
   - multiple → datasets grouped by PUBLISHER (namespace mode "owner")
   Then: what namespace value(s)? (e.g. "reference", or "worldbank, eurostat")

Note for the user when relevant: search is a static client-side list over datasets.json for now; a live backend (CKAN) can be wired in later with /portaljs-connect-ckan without changing URLs.

Round 3 — Showcase / views:

Round 3 of 3 — each dataset's showcase page (/@<namespace>/<slug>).
Every showcase already shows metadata + a data preview + a Download & API section.
For the dataset(s) above, do any need an extra view?
  - a chart (line/bar/area/pie/scatter) → added later with /portaljs-add-chart
  - a map (GeoJSON on Leaflet)          → added later with /portaljs-add-map
(Press Enter / "use defaults" for metadata + preview + download only.)

Defaults if a round is skipped: description "An open data portal."; no datasets; NAMESPACE_TYPE = 'theme' with namespace value reference; no extra views.

2. Confirm the brief before building

Echo a short brief back and wait for a yes:

Here's the plan — say "go" to build, or correct anything:
  • Name:        PROJECT_NAME  (slug: PROJECT_SLUG)
  • Description: DESCRIPTION
  • Namespace:   NAMESPACE_TYPE — value(s): NS_VALUES
  • Datasets:    <list, or "none — add later with /portaljs-add-dataset">
  • Views to add after scaffold: <charts/maps per dataset, or "none">

Derive PROJECT_SLUG from PROJECT_NAME (lowercase, hyphenated, no special chars, e.g. auckland-open-data).

3. Resolve the template source

This skill works both inside a clone of the portaljs repo and from any other project. Default to fetching the template remotely (always the latest). Use a local checkout only when you are genuinely inside an up-to-date portaljs repo AND not scaffolding into it. The default — and currently only — variant is examples/portaljs-catalog.

TEMPLATE_VARIANT="examples/portaljs-catalog"

# Default: fetch the latest template from GitHub. Override the ref with
# PORTALJS_TEMPLATE_REF (branch, tag, or commit); defaults to main.
TEMPLATE_MODE="remote"
PORTALJS_TEMPLATE_REF="${PORTALJS_TEMPLATE_REF:-main}"

# Use a LOCAL checkout only when BOTH hold (otherwise stay remote):
#  1. the resolved repo has the CURRENT template — verified by the @-namespaced
#     route file pages/[owner]/[slug].tsx. An old clone without it would scaffold a
#     stale, non-namespaced portal (pages/datasets/[slug].tsx) — issue #1556.
#  2. we are NOT scaffolding inside that repo (never create a portal inside the
#     framework repo itself).
if GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) \
   && [ -f "$GIT_ROOT/$TEMPLATE_VARIANT/pages/[owner]/[slug].tsx" ]; then
  case "$(pwd)/" in
    "$GIT_ROOT/"*)
      echo "Inside the portaljs repo — fetching the template remotely instead of copying in place." ;;
    *)
      TEMPLATE_MODE="local"
      TEMPLATE_DIR="$GIT_ROOT/$TEMPLATE_VARIANT" ;;
  esac
fi

4. Materialize the template

First, check the destination does not already exist. If ./$PROJECT_SLUG is non-empty, don't error out blindly — ask the user for a different name or whether to remove the existing directory, then proceed with their answer:

if [ -d "./$PROJECT_SLUG" ] && [ "$(ls -A "./$PROJECT_SLUG" 2>/dev/null)" ]; then
  echo "DIR_EXISTS: ./$PROJECT_SLUG already exists and is non-empty."
fi

If it exists, ask: "./PROJECT_SLUG already exists. Use a different name, or remove it and continue?" and act on the reply.

Then materialize, depending on the resolved mode:

if [ "$TEMPLATE_MODE" = "local" ]; then
  cp -rP "$TEMPLATE_DIR" "./$PROJECT_SLUG"
  # Remove build artifacts that must not be copied
  rm -rf "./$PROJECT_SLUG/node_modules" "./$PROJECT_SLUG/.next"
else
  # tiged (maintained degit fork) fetches a subdirectory of a repo with no git
  # history or node_modules. NOTE: plain `degit` is NOT reliable here — when its
  # tarball fetch fails it silently falls back to a full `git clone` that ignores
  # the subdirectory, dropping the WHOLE monorepo into the target (exit 0). tiged
  # extracts the subdirectory correctly.
  npx --yes tiged "datopian/portaljs/$TEMPLATE_VARIANT#$PORTALJS_TEMPLATE_REF" "./$PROJECT_SLUG"
fi

If the remote fetch fails (bad ref, network, or tiged unavailable), tell the user plainly and ask how to proceed (retry / different ref / check network). The scaffolded portal (Next.js) requires Node.js >=22; npx tiged itself runs on older Node, but use >=22 to match the template. (The resolver already defaults to remote when no current local template is found, so a missing or stale local checkout falls through to the latest template automatically.)

5. Substitute placeholder tokens

Replace all occurrences of the placeholder tokens in every file under ./$PROJECT_SLUG/:

| Token | Replace with | |-------|-------------| | __PROJECT_NAME__ | PROJECT_NAME | | __PROJECT_SLUG__ | PROJECT_SLUG | | __DESCRIPTION__ | DESCRIPTION |

Use perl -pi (portable across macOS and Linux). Escape values first so that /, \, and & in the inputs don't break substitution:

# Escape any / or \ in values for use as perl replacement strings
esc() { printf '%s' "$1" | perl -pe 's{([/\\])}{\\$1}g'; }
NAME_ESC=$(esc "$PROJECT_NAME")
SLUG_ESC=$(esc "$PROJECT_SLUG")
DESC_ESC=$(esc "$DESCRIPTION")

find "./$PROJECT_SLUG" -type f \( -name "*.tsx" -o -name "*.ts" -o -name "*.json" -o -name "*.js" -o -name "*.css" -o -name "*.md" -o -name ".lfsconfig" \) \
  | xargs perl -pi -e "
      s/__PROJECT_NAME__/$NAME_ESC/g;
      s/__PROJECT_SLUG__/$SLUG_ESC/g;
      s/__DESCRIPTION__/$DESC_ESC/g"

.lfsconfig carries the __PROJECT_SLUG__ token in its Git LFS endpoint URL (large data is served via Giftless → R2 — see the template README's "Large data" section), so it is included in the substitution above.

Optionally tailor the SUGGESTED_QUERIES array near the top of pages/index.tsx to the portal's topics (from Round 1) — these are the suggested-search chips under the hero.

Branding is a placeholder. The template ships with the PortalJS mark as default branding (favicon, navbar logo with a hover-spin, and PWA/social icons) so a fresh portal looks intentional out of the box. __PROJECT_NAME__ substitution already sets the navbar's brand text. The icon files are deliberately swappable — tell the user they can replace public/icon.svg, public/favicon.ico, public/apple-touch-icon.png, and public/icon-512.png with their own marks (no code change needed; the links live in pages/_document.tsx and components/Navbar.tsx). Do not leave a client portal permanently wearing the PortalJS logo.

6. Set the namespace mode

Edit ./$PROJECT_SLUG/lib/datasets.ts and set NAMESPACE_TYPE from the interview: 'theme' for a single publisher (datasets grouped by subject) or 'owner' for multiple publishers (datasets grouped by who published them). The default in the template is 'theme'.

# Set to 'owner' only if the interview chose a multi-publisher portal.
perl -pi -e "s/export const NAMESPACE_TYPE: 'theme' \\| 'owner' = '[a-z]+'/export const NAMESPACE_TYPE: 'theme' | 'owner' = 'owner'/" "./$PROJECT_SLUG/lib/datasets.ts"

7. Seed datasets captured in the interview

The template ships with three sample entries in datasets.json (under namespace reference). If the user named real datasets in Round 2, replace the samples with their data; if they said "none yet", clear the manifest to [] so the /search page shows its empty state.

For each captured dataset, run the /portaljs-add-dataset flow (preferred — it handles fetch/copy, format detection, and manifest append), or append directly: drop the file in ./$PROJECT_SLUG/public/data/ and add an entry to datasets.json shaped like:

{
  "slug": "<url-safe-slug>",
  "namespace": "<the NS value from Round 2>",
  "name": "<Human Name>",
  "description": "<one line>",
  "file": "<file-in-public-data>",
  "format": "csv"
}

Use the namespace value(s) from Round 2 (the portal's NAMESPACE_TYPE mode). No per-dataset page is needed — pages/[owner]/[slug].tsx renders every entry at /@<namespace>/<slug> automatically.

8. Install dependencies

cd "./$PROJECT_SLUG" && npm install

Tell the user first: Installing dependencies (2–5 min on cold cache)...

If npm install fails, report the error plainly and a

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars2.4k
CategoryDevelopment
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