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.