Add a NodeNorm skill for coding agents, served at /llms.txt

[gaurav]

Makes NodeNorm usable from a coding agent without the agent having to reverse-engineer the API from its OpenAPI schema.

Stacked on #403 — targets improve-documentation, not main, because the skill links to documentation/Babel.md which that PR introduces. Merge #403 first and this retargets cleanly.

Before merging

• Run a real docker build. Docker was not available in the session that wrote this, so the image was never built — see Not verified. The COPY ./skills skills line is the only thing standing between this and a /llms.txt that works locally and 404s in every deployment.

docker build -t nn-skill-check .
docker run --rm nn-skill-check python -c \
  "from node_normalizer.config import SKILL_PATH; assert SKILL_PATH.is_file(), SKILL_PATH; print('skill present:', SKILL_PATH)"

• Merge Document where NodeNorm's data comes from, and serve the API docs that were being discarded #403 first, or retarget this to main.
• Repoint the master URLs at main. Done — 27 links across both branches. The 25 that predate this PR are fixed on Document where NodeNorm's data comes from, and serve the API docs that were being discarded #403 (endpoint descriptions in server.py, Babel.md, API.md, openapi.yml, and the notebook's Colab badge); the two in this PR's own files — skills/nodenorm/SKILL.md and the install curl in documentation/LLMs.md — are fixed here. biolink-model/master is deliberately untouched, since biolink-model really does default to master. Note the two new targets 404 until Document where NodeNorm's data comes from, and serve the API docs that were being discarded #403 and this PR merge, which is correct: an install URL should hand people the merged file rather than a branch that will be deleted.

Why a skill rather than MCP or a CLI

#403 already fixed the reference problem: every endpoint has a real description, the response schema is documented, examples are served. What an agent still lacked is judgement — when to reach for NodeNorm at all, which conflation flags to set, how to batch, and which behaviours fail silently rather than erroring.

• MCP server — NodeNorm is an unauthenticated public API whose useful surface is essentially one endpoint. A server to build, host, version and register, plus per-user configuration, buys little. NameRes reached the same conclusion: its "Add MCP endpoints" issue (NameResolution#251) produced a skill file instead. Worth revisiting if usage shows agents actually struggling.
• Python package / CLI here — a new packaging and release surface in a repo that ships a service and a loader, and Translator_sdk already wraps NodeNorm. The skill teaches batching against a documented contract instead.

What is in it

• skills/nodenorm/SKILL.md — the skill, in the <name>/SKILL.md + frontmatter layout Claude Code actually discovers. Body is plain Markdown, usable pasted into any agent.
• GET /llms.txt — the same document served by the instance itself, frontmatter stripped, linked from the OpenAPI description. An agent given only a base URL can bootstrap. One copy of the text: the route reads the skill file directly.
• documentation/LLMs.md + a README pointer.
• tests/frontend/test_llms_txt.py — 4 tests, no Redis needed.

Note the Dockerfile change. The image copies only node_normalizer/, config.json, redis_config.yaml and load.py, so without COPY ./skills skills this route works locally and 404s in every deployment.

Every claim is measured, not remembered

The numbers in the skill came from hitting the live RENCI instance, and the three traps it exists to prevent were all confirmed there:

Trap	Evidence
GET/POST conflation defaults differ (#398)	Identical query returns 206 equivalent identifiers via GET, 30 via POST
/get_setid parameters are inverted and silently ignored	GET takes conflation, POST body takes conflations; wrong name returns HTTP 200 with an unconflated hash and empty conflations
Prefix matching is a coin flip	The DMD clique has three ENSEMBL: entries — one gene, two proteins

The /get_setid one matters most: anyone comparing a gene against its protein with default flags concludes they are different concepts, with no error.

Validation

The skill was tested twice by agents given only the skill file plus network access, with no repo access.

First pass completed both target use cases and found no factual errors, but hit two traps — and both were the documents fault. /get_setid was a one-line stub whose "set both flags on every request" advice generalised wrongly, and the flagship recipe told it to match on prefix, which nearly returned ENSP00000288447 as "the Ensembl ID". Both fixed.

Second pass made zero wrong turns — but correctly pointed out I had tested it on its own worked examples, so it was really checking whether the doc could be copied, not whether it taught the model. Its substantive finding: the skill stated "30 vs 206" three times without ever giving the rule those numbers illustrate.

So the last commit adds the rule, measured across all four flag combinations for seven CURIEs: only the conflation matching the concepts kind does anything; the other flag is a no-op. Genes and proteins move only with conflate; chemicals only with drug_chemical_conflate; diseases and phenotypes not at all.

One reported finding was wrong and deliberately not applied — include_taxa was said to populate only individual entries. It populates both a top-level taxa array and the entries. Agent findings were verified rather than taken on faith.

Not verified

The Docker image was never built. Docker was not running. Instead the container layout was replicated (/code with node_normalizer/ and skills/ alongside) and SKILL_PATH confirmed to resolve, and there is no .dockerignore to exclude skills/ — so the COPY should be correct, but that is inference, not evidence. Please run the build in Before merging above.

Follow-ups filed

#404 (the Dockerfile still pins --root-path /1.3, the last source of the deprecated prefix), NameResolution#290 (that repos skill install instructions point at a path Claude Code does not discover, so the two services can converge).

🤖 Generated with Claude Code