How to use the Ontology Term Resolution agent skill

What an agent skill is and what this one makes the agent do

An agent skill is a folder containing a SKILL.md instruction file plus optional scripts and reference notes. When a request matches the skill's description, the agent reads these instructions and uses the bundled scripts instead of relying only on its own memory.

This skill targets one specific failure: an agent writing an ontology ID from memory. The skill's rule is never to write an ID from memory and never to accept one without checking it. For a label such as a tissue or cell type, the agent searches the EBI Ontology Lookup Service (OLS4), then validates the chosen ID for existence, currency and label, and checks the definition against the sample and target schema before accepting it.

• Resolves free-text labels to candidate term IDs (resolve_terms.py)
• Validates existing IDs for not_found, obsolete, label_mismatch and wrong_ontology problems (validate_terms.py)
• Checks prefixes and identifier patterns via Bioregistry (lookup_prefix.py)
• Maps lab shorthand such as PBMC through ZOOMA, always followed by an OLS check (map_terms.py)

Install the skill by ZIP or in the Claude apps

Download the ZIP for this skill from the page you are reading. For a personal install, unzip it into ~/.claude/skills/ so the folder sits at ~/.claude/skills/ontology-term-resolution. For a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal install: ~/.claude/skills/
• Project install: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills

Check the requirements before running it

The scripts use only the Python standard library, so there are no packages to install. They need Python 3.11 or newer and network access to ebi.ac.uk (OLS4 and ZOOMA), bioregistry.io and resolver.api.identifiers.org. No API key is required.

Because the lookups are live internet calls, the skill will not work on a machine without network access.

• Python 3.11 or newer
• Network access to ebi.ac.uk, bioregistry.io and resolver.api.identifiers.org
• No API key and no third-party Python packages

Trigger the skill with natural requests

You do not need to name the skill. The agent is directed to use it when you ask for an ontology term or ID, mention a CURIE or controlled vocabulary, name an ontology such as UBERON, CL, MONDO, HPO, EFO, ChEBI or NCBITaxon, or ask to annotate a tissue, cell type or disease. Naming a repository such as GEO, ENA, BioSamples, CELLxGENE, HCA or ISA-Tab also fits the skill's scope.

Be specific about the direction: say whether you want an ID found for a label, or an existing ID checked.

• "Find the UBERON term for left ventricle."
• "Check whether EFO:0001067 is still current and correctly labelled."
• "Annotate this tissue column with ontology IDs for a GEO submission."
• "Is HPO a valid prefix, or should I use HP?"
• "Audit this metadata.tsv for obsolete or mislabelled term IDs."

Resolve a label to a term ID

Run the resolver from the skill's scripts folder, constraining the search to the ontology that should define the term. The output lists the match type and whether the hit comes from its defining ontology. Read the match_type before using a result: exact_label and exact_synonym only show lexical agreement, not correct sample context.

For a column of names, use --exact-only so that anything without an exact hit is reported rather than guessed.

• Unresolved output is a legitimate result, not a failure.
• Searches return bounded candidate lists (--top), not exhaustive ambiguity checks.
• Fuzzy matches such as partial, related or broad synonyms require manual curation.

Validate IDs and use it as a CI gate

The validator checks each ID and reports a status such as ok, obsolete, not_found, label_mismatch or wrong_ontology, with a replacement ID when OLS gives one. Its exit code is 1 if anything failed, 0 otherwise, and 2 on usage or network trouble, so it can gate a metadata file in continuous integration.

Use --strict to turn warnings into failures, --expect-ontology to stop a term from another ontology entering a column, and --branch to require descendants of a root term.

• ok: exists, is current and is consistent with what is asserted
• warn statuses: matched_synonym, imported_only, not_a_class
• fail statuses: not_found, obsolete, label_mismatch, wrong_ontology, wrong_branch, malformed_curie
• not_found means absent from this OLS lookup, not proof that the term does not exist anywhere

Check prefixes and identifier patterns

Use the prefix lookup to confirm whether a prefix is real, whether a local ID matches the recorded pattern, and what the preferred prefix is. Bioregistry accepts synonym prefixes, so HPO maps to the preferred prefix HP. Prefix lookup answers only identifier questions; it does not tell you whether a term exists or is obsolete.

Safety notes: scripts and network calls

This skill runs Python scripts and makes live network requests to public services: EBI OLS4 and ZOOMA, Bioregistry, and Identifiers.org. The skill declares allowed tools as Read, Write, Edit and Bash, so review the scripts before you run them in a sensitive environment. The skill does not need an API key, and its source describes the requests as unauthenticated public reads.

Your input values, such as label text or identifiers from your files, are sent to these services as query strings. If your labels are confidential, check that this is acceptable before running the skill on them.

• Scripts run locally under Python 3.11+ and use only the standard library
• Network calls go to public endpoints and send your query text to them
• Failures from OLS are reported as service errors, not as empty scientific results