Add an agent skill for NameRes, served at /llms.txt

[gaurav]

Gives NameRes an agent skill that a coding agent can load to use this API properly, and serves it from the API itself at GET /llms.txt.

Based on #262 (improve-documentation), so the skill can reference documentation/Babel.md and the rest of that work. Retarget to main once #262 merges.

Closes #290.

What's here

skills/nameres/SKILL.md — moved from a flat skills/nameres.md and given name/description frontmatter, because Claude Code discovers skills as <name>/SKILL.md directories and never loaded the flat file (#290). The description names trigger situations rather than describing the service, since that is what the model matches on.

GET /llms.txt — serves that same file with its frontmatter stripped. One copy of the text, and the instructions an instance hands out always match the API answering the queries. Linked from the OpenAPI info.description so an agent given only a base URL can find it.

LookupResult field descriptions — api/server.py had 40 description= strings, every one on a request parameter, and none on the response model. An agent reading /openapi.json got a well-documented request and a completely unexplained response. The descriptions carry the traps, because that schema is what an agent reads without being told to.

documentation/LLMs.md — rewritten to install-and-maintain only. Its old install instructions could not work, and its "Example Workflows" section was a second copy of the API surface built from unverified values; it is deleted rather than fixed.

Corrections, all checked against a live instance

The skill's API-surface claims held up well — biolink_type vs biolink_types, POST-takes-query-params, the biolink: prefix asymmetry, taxon_specific inclusion were all correct. The example values did not:

Claim	Reality
/lookup?string=diabetes → MONDO:0005148 "diabetes mellitus"	MONDO:0005148 is "type 2 diabetes mellitus" (21 identifiers, not 125). "diabetes mellitus" is MONDO:0005015.
CHEBI:46195 labelled "paracetamol", via DrugChemical conflation	It is labelled "Acetaminophen", and the mechanism was wrong — acetaminophen/paracetamol are one compound by ordinary synonymy; DrugChemical joins drug products to active ingredients.
Scores around 42.5 / 38.1 / 51.2	Real scores run into the thousands (3770, 6872). Quoting any of them invites thresholding on a value with no fixed scale.
MONDO:0005044 "hypertension"	Correct, as it happens.

The diabetes result is now the skill's worked example for not trusting the top hit, because the real answer teaches the lesson better than the invented one did: the winner is UMLS:C0011847 "Diabetes", a leftover-UMLS singleton with clique_identifier_count: 1, ahead of the concept anyone actually wants.

Also fixed the same MONDO:0005148 error where it appears in documentation/API.md.

Content that became a link

The skill was accumulating copies of things that live elsewhere. Now: the scoring boost table → Scoring.md (which already owned it, and the copy was a revision stale), the exhaustive parameter reference → API.md, why cliques look the way they do → Babel.md. The base URL was hardcoded 8×; it is stated once and every example uses a bare path, which is also what makes the document correct when served at /llms.txt from a non-RENCI instance.

The rule is written down in CLAUDE.md: the skill carries how to call the API, how to read the result, and the traps that silently produce a plausible wrong answer — anything a Babel rebuild could falsify gets linked instead.

⚠️ Verified against ITRB CI, not against code-matching data

This needs re-testing against NameRes Exp before shipping. No instance currently serves both recent data and a NameRes matching this repo:

Instance	State
name-resolution-sri.renci.org (dev)	503 throughout this work
name-lookup.ci.transltr.io	Used for verification. Babel 2025sep1, NameRes v1.5.2
name-lookup.transltr.io (prod)	Solr index dated 2024-11-15; /status has no babel_version, nameres_version or biolink_model at all
name-resolution-exp.apps.renci.org (Exp)	Corresponds to this repo's code — unreachable, RENCI is down

Two concrete divergences between ITRB CI and this repo that the examples could hide:

1. /status response shape differs. CI (v1.5.2) nests the Solr fields under "solr" and adds a recent_queries block; this repo returns them flat. The skill therefore documents only babel_version, nameres_version and the conflations, and says older deployments may omit them — it does not document the shape.
2. /synonyms on CI returns names_exactish. The current schema has that field stored="false", so this repo does not return it. Harmless, but it means a response captured from CI is not byte-identical to one from this code.

Before this ships, someone should re-run the skill's examples against Exp and confirm the diabetes disambiguation example still holds.

Out of scope

• MCP — Add MCP endpoints #251. A skill is text with no runtime, deployment or auth, and works with any agent that can make an HTTP request; an MCP server would need all three to wrap an API that is already REST with an OpenAPI schema. Its tool descriptions would be written from this same content, so this is a prerequisite rather than a competitor.
• A Python SDK — the existing Translator_sdk/name_resolver.py is fine; expanding it adds a second API surface to version and helps only Python callers.
• Giving /synonyms a response model — Harmonize the /lookup and /synonyms response shapes #291, which has to settle the field names first.

Verification

• 43 tests pass (up from 35 on Improve NameRes documentation: Translator Guide, Babel data guide, and doc drift fixes #262) against a local Solr 9.10.1 with the checked-in configset.
• tests/test_llms_txt.py — the file exists, frontmatter is valid and matches its directory, /llms.txt is served as text/plain with frontmatter stripped, a missing file 404s with an actionable message, the links are absolute, and specific traps survive rewrites.
• The Docker path was verified, not assumed. No Dockerfile change is needed here (COPY . /repo/NameResolution, and .dockerignore does not exclude skills/), but that is the one failure mode that passes locally and 404s in every deployment, so: docker build, assert SKILL_PATH.is_file() inside the image (resolves to /repo/NameResolution/skills/nameres/SKILL.md), then curl /llms.txt from the running container → 200 text/plain.
• tests/test_docs_links.py's master-branch ban now also catches the raw.githubusercontent.com form the install instructions use.

Follow-up

If #231 (track-recent-times) merges after this, /status gains recent_queries and the skill's "Which data am I querying?" section should be revisited.