Skip to content
Get packs

Guide · Agent skill

How to use the NCATS ARAX Knowledge Graph Lookup agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The ncats-arax skill lets an AI agent query the public NCATS Translator ARAX service, a biomedical knowledge graph, for relationships between entities such as chemicals, genes and diseases. It is built for showing candidate connections with their sources, not for drawing conclusions. This guide explains what an agent skill is, how to install this one, how to ask for a lookup in plain language, and how to read the saved results safely.

NCATS ARAX Knowledge Graph LookupK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download the ZIP. Get the ncats-arax ZIP from this page.
  2. 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  3. 3Confirm Python and network access. Make sure Python 3.10 or newer is installed and that outbound HTTPS to arax.transltr.io is allowed.
  4. 4Ask a public lookup question. Describe a public biomedical relationship in plain language and mention ARAX or the knowledge graph.
  5. 5Review the normalized identifier. Check the proposed CURIE, name and category before a graph query runs.
  6. 6Inspect the saved output. Open summary.json for bindings and provenance, and response.json for the exact payload, then verify important candidates elsewhere.

What an agent skill is and what this one does

An agent skill is a folder containing instructions (SKILL.md) and optional scripts and reference files that an AI agent can load when a task matches the skill's description. This skill's folder is skills/ncats-arax and includes SKILL.md, references/query-contract.md and references/output-schema.md, plus a Python client in scripts/arax_client.py.

With the skill active, the agent can normalize a free-text term to a reviewed identifier, run a typed one-hop lookup, run an endpoint-pinned two-hop lookup, or run explicitly selected-provider federation. It saves the exact request and response and summarizes the supporting sources and provenance.

Install the ncats-arax skill

Download the ZIP for this skill from this page. Then choose one of the two install routes below.

For a personal install across projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Either way the skill folder should end up containing SKILL.md.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Check your requirements

The skill needs Python 3.10 or newer and outbound HTTPS access to arax.transltr.io. The client uses only the Python standard library and needs no API key or account.

The skill's compatibility note warns that queries and caller metadata may be publicly visible. Only use it for public, nonsensitive research questions.

  • Python 3.10 or newer
  • Outbound HTTPS to arax.transltr.io
  • No API key or account needed

Trigger the skill with a natural request

You do not need to name commands. Describe a public biomedical relationship question and mention ARAX or the knowledge graph. The skill is meant for lookups such as which genes a compound affects, or how a compound may connect to a disease through one intermediate gene.

Ask for the scope you want. Name providers only if you want federation; otherwise the default is RTX-KG2 lookup. Say if you want the output saved so you can inspect it later.

Good requests are specific: a named compound, a Biolink type, and a relationship. Avoid asking for predictions, rankings or medical advice, because the skill excludes those.

  • Example: Using ARAX, find gene relationships for the compound ivacaftor, as a public lookup with saved output.
  • Example: Check the ARAX knowledge graph for chemicals that affect ABL1, and keep the sources.
  • Example: Normalize the term ivacaftor and show me the CURIE and category before querying.

Run the commands the skill uses

The skill runs a preflight check first, which reads the production OpenAPI without making a biomedical query. A normalization step reviews an identifier without triggering a graph query. A one-hop lookup pins at least one endpoint and types both nodes. Every graph query requires a new or empty output directory and the public-query acknowledgement flag.

You can also rerun a saved query offline. The summarize command rebuilds a bounded summary from saved request and response files without network access.

  • Lookup mode is the default, fixed to infores:rtx-kg2, and returns 20 results unless you set --result-limit between 1 and 50.
  • Two-hop lookup uses exactly one typed, unpinned intermediate node and right-first expansion by default.
  • Federation accepts two to five named providers and defaults to 50 results.
python skills/ncats-arax/scripts/arax_client.py preflight

Read the saved results

The output directory holds request.json, response.json, summary.json and manifest.json. Check summary.json for bounded bindings and provenance, and response.json for the exact TRAPI payload.

Results are unscored. Their order is response order, not rank. A zero result means nothing was returned under these constraints, not that no relationship exists. Treat publication_availability: not_returned as missing metadata.

Trace aggregator edges back to primary sources before counting them as corroboration, because several providers can redistribute the same record.

  • Follow query-edge bindings rather than summarizing the whole graph.
  • Treat provider errors as warnings; a run with partial results exits 7 and is marked partial.
  • An explicit non-success ARAX status exits 6 with the raw response kept.

Verify candidates outside ARAX

Every returned path is a candidate for later checking. Confirm anything important with the literature and authoritative databases before relying on it. The skill does not validate mechanisms or give clinical recommendations.

What people use it for

  • Listing public chemical-to-gene relationships for a named compound, with the supporting sources.
  • Running a two-hop check from a compound through one gene to a disease, with the intermediate node left open.
  • Comparing the default RTX-KG2 lookup with a federated run that names specific providers.
  • Teaching how Biolink types and qualifiers constrain a knowledge-graph query.
  • Keeping a reproducible record of a public lookup by saving the exact request and response.

Frequently asked questions

How do I install the ncats-arax skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills.

What do I need to run it?

Python 3.10 or newer and outbound HTTPS access to arax.transltr.io. The client uses only the Python standard library and needs no API key or account.

Is the ncats-arax skill free?

The skill is published under the MIT licence. The source does not state pricing for the ARAX service beyond noting that no API key or account is required.

Can I use it for patient or confidential research?

No. The skill says queries and caller metadata may be publicly visible, so use it only for public, nonsensitive research questions. Do not submit patient information, unpublished compound programs or proprietary hypotheses.

Why does a query return no results?

A zero result means nothing was returned under the given constraints, not that no relationship exists. Try reviewing the identifiers and category, or run a new query explicitly with another expansion order; the skill does not change settings silently after an empty result.

How does this compare with other knowledge-graph tools?

This skill is focused on typed, bounded lookups against one ARAX endpoint, with saved provenance. It deliberately excludes ranking, inference, open-ended pathfinding and natural-language-to-query conversion, so use a different tool if you need those.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits researchers, data scientists and students who want traceable, typed lookups against the public ARAX knowledge graph and who will verify results themselves. It is a poor fit for clinical or patient-specific decisions, confidential research, or anyone who wants ranked predictions or open-ended pathfinding.

Download the skill