report-catalog-issue
Skill11 starsChanged 32 days agoApache-2.0View on GitHub
Report a problem with a catalog registered in the Portolan registry by opening a catalog feedback issue against it.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- catalog-graderSkill
- customize-portolan-browserSkill
- enrich-metadataSkill
- git-backed-catalogSkill
- portolan-bootstrapSkill
- portolan-cliSkill
- portolan-migrateSkill
- portolan-thumbnailsSkill
- reading-portolanSkill
- register-catalogSkill
- sourcecoopSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Use it for problems with the data a catalog serves.
- Distinctive: line 23
Only a registered catalog can be reported.
- Very specific: line 44
If the script exits 1, stop.
- Very specific: line 62
Use curl and jq to show metadata fields, or DuckDB to inspect data.
- Distinctive: line 69
Never paste output you did not produce.
- Very specific: line 132
If the issue comes back with a comment that the catalog is not registered, the id was wrong.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- drift: depends-on: portolan-registry, rashid -->Report a Problem with a Registered Catalog
You found something wrong with a Portolan catalog while reading it. The problem may be one of these:
- a license that misdescribes the data
- a collection whose schema contradicts its items
- an asset that does not open
- a description that documents something else
This skill files that report as a catalog feedback issue on portolan-registry. The registry mails the person who registered the catalog.
Use it for problems with the data a catalog serves. A problem with the registry itself, its crawl, or its export is an ordinary bug report on the same repo.
Step 1: Resolve the catalog against the registry
Only a registered catalog can be reported. The registry export lists every one. Each child link includes the registry id.
# Accepts either the registry id or the catalog.json URL
NEEDLE="pergamino-ide"
curl -fsSL https://raw.githubusercontent.com/portolan-sdi/portolan-registry/refs/heads/main/exports/catalogs.json \
| NEEDLE="$NEEDLE" python3 -c "
import json, os, sys
needle = os.environ['NEEDLE'].rstrip('/')
links = [l for l in json.load(sys.stdin)['links'] if l.get('rel') == 'child']
for l in links:
if needle in (l.get('portolan_registry:id'), l.get('href', '').rstrip('/')):
print(l['portolan_registry:id'])
break
else:
print('NOT REGISTERED. Ids:', ', '.join(l['portolan_registry:id'] for l in links), file=sys.stderr)
raise SystemExit(1)
"If the script exits 1, stop. The catalog is not in the registry, so there is nobody to notify. Offer the register-catalog skill instead.
Step 2: Run the check that shows the problem
The report is worth nothing without evidence. Run a command against the live catalog and keep both the command and its output.
rashid check accepts a local path or published HTTPS URL and cites spec rule IDs in its findings. Inside a catalog managed by the CLI, use portolan check.
uvx --from 'rashid>=0.3.0,<0.4.0' rashid check ./catalog --summaryFor published catalogs, rashid follows links and runs live checks:
uvx --from 'rashid>=0.3.0,<0.4.0' rashid check "$CATALOG_URL" --summaryUse curl and jq to show metadata fields, or DuckDB to inspect data.
curl -fsSL https://data.source.coop/nlebovits/pergamino-ide/catalog.json \
| jq '{title, stac_extensions}'Never paste output you did not produce. If you cannot reproduce the problem now, say so to the user and stop.
Step 3: Compose the body
Write in Simplified Technical English. Run .claude/hooks/writing_check.py --print-rules in any portolan-sdi repo to read the rules. The gh issue create hook blocks a body that fails them. Lead with what is wrong and what should happen instead, in words a reader who did not follow your investigation understands in a minute. Put the evidence after that.
gh cannot fill an issue form, so write the headings the form renders. The registry's notifier reads the Catalog ID and Kind of problem sections by name. Those two spellings must be exact.
<!-- drift-sample: issue -->### Catalog ID
pergamino-ide
### Kind of problem
Schema
### What you found
The root catalog declares no `title` and no `stac_extensions`. Both are MUST fields. The registry lists the catalog by its slug and records no Portolan spec version. Add a `title` and the v0.2.0 schema URI to `stac_extensions`.
### How you hit it
```shell
$ curl -fsSL https://data.source.coop/nlebovits/pergamino-ide/catalog.json | jq '{title, stac_extensions}'
{
"title": null,
"stac_extensions": null
}
```
### Date observed
2026-08-11
### Tool or agent
curl 8.5.0Kind is one of: Data quality, Schema, Accessibility, Documentation, Other. A missing or wrong metadata field is Schema. A wrong README or description is Documentation. Data quality is for the values in the data files. Accessibility is for an asset that does not open or a host that fails range requests.
Report one problem per issue. File a second issue for a second problem. Fill the How you hit it block with the command you ran and its output. Do not describe the output in prose.
Step 4: Get approval, then file
Show the user the finished body and the catalog it names. Do not open the issue until they approve it. The report is public and it mails a third party.
gh issue create \
--repo portolan-sdi/portolan-registry \
--label catalog-feedback \
--title "pergamino-ide: root catalog declares no title or spec version" \
--body-file body.mdThe title states the catalog first, then the problem in a few words.
Step 5: report back
Give the user the issue URL. Tell them the registry mails the submitter of that catalog. Nothing about the catalog's registration or validity changes. Those come from the nightly crawl, not from feedback.
If the issue comes back with a comment that the catalog is not registered, the id was wrong. Correct the Catalog ID section, then ask a maintainer to re-apply the catalog-feedback label, which re-sends the notification.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

