Portolan skills

Overview · Quickstart · Installation · Skills · Evaluations

Overview

This repository gives your coding agent workflows for building, publishing, reviewing, and using Portolan geospatial data catalogs. Give your agent a source URL or a folder of files to turn into a documented catalog.

The skills cover data conversion, metadata research, Git-backed catalogs, map thumbnails, Source Cooperative uploads, catalog reviews, and data analysis. Each directory in skills/ contains a SKILL.md file. Some also include scripts and reference material. They follow the Agent Skills format, with installation options for Claude Code, Codex, Gemini CLI, and other agents.

evals/ contains the catalog-grader evaluation suite. pins.toml records the upstream versions the skills describe, and scripts/check_drift.py checks their commands and specification references against those versions. Catalog requirements come from the Portolan specification.

Quickstart

This example uses Claude Code and uv. Install both before you begin. For other agents, follow Installation, then adapt the skill invocation in the prompt.

1. Install the Portolan plugin and portolan-cli from your terminal:

   claude plugin marketplace add portolan-sdi/portolan-skills
   claude plugin install portolan@portolan-skills
   uv tool install portolan-cli
   portolan --version
   

2. Open a working directory and start a new session:

   mkdir my-catalog-work
   cd my-catalog-work
   claude
   

3. Run the bootstrap skill in the agent session. Replace the source placeholder with a data URL or local path:

   /portolan:portolan-bootstrap
   
   Build a Portolan catalog from .
   Use git-backed-catalog to create a GitHub repository for the metadata,
   with validation in CI and data files in object storage.
   Use the bootstrap guidance to research the source, convert the data,
   and write metadata, documentation, and map styles.
   Use portolan-thumbnails to generate and visually check the thumbnails.
   I plan to host the catalog and data on Source Cooperative; use
   sourcecoop for its account and authentication setup.
   Ask me for the repository names, license, and maintainer contact.
   Show me the plan and upload preview before publishing.
   

   If you use another storage provider, replace the Source Cooperative request with your destination. Source Cooperative hosting requires an account with write access to the destination repository.

4. Review the agent’s source research, proposed collections, license, and storage plan. The Git-backed workflow starts from the catalog template and keeps metadata under version control. Bootstrap directs this work to git-backed-catalog, which owns repository setup, validation, and publishing. Use the template’s publishing tools throughout that workflow.

5. After publication, open the catalog in the Portolan browser and check its maps, thumbnails, and download links. Ask your agent to use catalog-grader for a quality review, then register-catalog if you want to submit it to the registry.

See the CLI documentation for conversion and publishing commands. The thumbnail skill requirements include Node.js 24.12 or later, npm, and an agent that can view images. The Source Cooperative skill covers its CLI, access, and authentication setup.

Installation

Choose the instructions for your agent. Copy whole skill directories so the agent can use their scripts and reference files.

Claude CLI

For Claude Code, use the plugin commands in the quickstart, then start a new session. Skills use the portolan: prefix: /portolan:portolan-bootstrap builds a catalog, and /portolan:reading-portolan helps you use one.

See Claude Code plugin installation for installation scopes and updates.

Claude web and desktop apps

1. Open Customize, then Plugins.
2. Select Add, Add marketplace, then Add from a repository.
3. Enter portolan-sdi/portolan-skills and install the Portolan plugin.

See Use plugins in Claude for account and workspace requirements. For workflows that run local tools or process files, use Cowork or Claude Code with access to your working directory.

Codex

From the root of the project where you want to use the skills, run:

skills_checkout=$(mktemp -d)
git clone https://github.com/portolan-sdi/portolan-skills.git "$skills_checkout"
mkdir -p .agents/skills
cp -R "$skills_checkout"/skills/. .agents/skills/

Codex discovers skills in .agents/skills/. Invoke one by name, for example $portolan-bootstrap, or describe your task so Codex can select it. For installation across your projects, use ~/.agents/skills/ as the destination. See the official skill documentation for discovery and invocation details.

Gemini CLI

Install a skill at user scope:

gemini skills install https://github.com/portolan-sdi/portolan-skills.git \
  --path skills/portolan-bootstrap --consent

Repeat the command with a directory from the skills list for each skill you need. For the quickstart, also install git-backed-catalog, portolan-cli, portolan-thumbnails, and sourcecoop. Add --scope workspace to install for the current project. See Gemini CLI skills for discovery and management.

Other agents

If your agent supports Agent Skills, install the skill directories in its documented location. Otherwise, add the relevant SKILL.md content to its custom instructions and make the supporting scripts and references available in the workspace.

Skills

Evaluations

Use these evals with the workflow in Automating eval design and hillclimbing with Claude. Measure a baseline, change a skill, and compare the results. The goal is to build evaluations for every skill and improve both the skills and their evaluations over time.

The current suite covers catalog-grader. The catalog-grader eval tests the skill against saved catalog facts and maintainer-approved expected results. Scorer tests run without model calls:

node --test evals/*/*.test.mjs

For a full evaluation, you need Node.js 20 or later, uv, and authenticated Claude Code 2.1.300 or later. Each case starts a paid Claude Code session. Follow the eval authentication instructions before running these commands from this repository’s root:

1. Download the frozen inputs and run the unchanged skill as a baseline:

   evals/_lib/frozen.sh fetch evals/catalog-grader
   node evals/catalog-grader/run-eval.mjs \
     --flow .claude/hillclimb/catalog-grader \
     --variant baseline --model claude-opus-5-5 \
     --reps 2 --concurrency 3
   

   If the runner requests harness approval, review the files it lists, then repeat the command with --approve-harness for one run.

2. Edit the skill, then repeat the runner command with --variant v1. Keep the model, case selection, and repetition count the same for comparison.

3. Build the report and print both summaries:

   node evals/_lib/build-report-lite.mjs .claude/hillclimb/catalog-grader/
   python3 evals/catalog-grader/summary.py \
     .claude/hillclimb/catalog-grader/baseline \
     .claude/hillclimb/catalog-grader/v1
   

   Open .claude/hillclimb/catalog-grader/report.html to compare the results. Include both summaries in your pull request’s Verification section.

You can also run the Eval catalog-grader workflow, which uploads the results as an artifact. See the evaluation guide for frozen input releases and changes to expected results.

Before submitting a change, check the skills against the pinned upstreams:

uv run scripts/check_drift.py

License

Apache-2.0