Your first data page in ten minutes

Install the plugin

The skill is the part your agent uses. It teaches it to look for what is already known about a dataset before touching it, to write down what it learns, and to offer the public-safe part back. Everything below can be done by hand, but this is what makes it happen without being asked.

Start a new session afterwards. Not using Claude Code? Copy skills/ergo/ into whatever your agent reads.

Vendor the tool

One file, no install, no dependencies. Commit it: the version it was vendored at is recorded in its header, and a repository that carries its own validator can still be checked in five years.

Scaffold a page

One page per dataset, named after its slug. The template is a to-do list: it does not validate until you have filled in who publishes the data, where it comes from, and what the pitfall is.

Fill the manifest, and write the pitfall first

Publisher, source_urls, status — and pitfall: one sentence naming the single thing most likely to trip up somebody who touches this data cold. It is required because it is the line that travels furthest, into the index and into an agent's context, often without the rest of the page.

Add subject too, if the dataset has a landing page. It is the identity claim — what dataset this is, as opposed to where you fetch it — and it is how anyone else's page about the same data can be found alongside yours.

Register the issue you already know about

Title it by the symptom, not the diagnosis: "rate cells are strings", not "inconsistent typing" — that is how the next person searches. Then the four required judgments: what happens if you ignore it (effect), what kind of problem it is (type), whether it is still true (status), and where it applies ([issue.scope]).

If it is a misleads or a context issue, write the misuse: the wrong conclusion a careless-but-reasonable reader would publish. That sentence is usually the most valuable line on the page.

Link the issue to the code that handles it

If you have already worked around it, set status = "mitigated" and list the code in handled_by. Then put the anchor comment beside the workaround. Add a few words about why the code looks odd if it helps; anything longer belongs on the page, not in the comment.

Now grep -rn "ergo: my-dataset" finds every workaround in the repository, and deleting either half fails the check instead of quietly changing a number.

Record how you checked it

A [validation] block: the date, the method, and the result with numbers in it. Write "7 of 7 spot figures match within rounding" rather than "we checked" — a later reader can re-run the first one and see whether it still holds.

Generate the index

One row per dataset — status, issue counts by effect, core flagged, and the pitfall. Regenerate it on commit; never hand-edit it.

Point your agents at it

Agents do not discover documentation at well-known paths; they go where they are pointed. Two or three lines in CLAUDE.md or AGENTS.md is what makes the rest of this work — the digest and the pages carry the weight.

## Data documentation

Every dataset we ingest has an ergo data page in `docs/data/`, indexed by
`docs/data/INDEX.md`. Read the page before writing code against a dataset:
issues carry stable ids, the ids are anchored in the code that works around
them, and `python3 tools/ergo.py check docs/data --repo .` validates that
contract.

For agents that maintain the pages as well as read them, copy the skill into your skills directory. It covers both roles: consulting the registry before writing code, and registering an issue at the moment of discovery.

Put the check in CI

--require-manifest closes the directory, so a prose file that quietly stops being a data page is an error rather than a page that silently disappears from the check. Add --strict once you have cleaned the warnings, and warnings fail too.