How to use the PrimeKG knowledge graph lookup agent skill

What the primekg skill makes the agent do

PrimeKG is a knowledge graph that links typed biomedical entities such as genes, drugs, diseases and phenotypes. The skill gives the agent a helper script that searches this graph in a downloaded CSV file and reports the associations it records.

The agent can resolve an entity name to a node, list its direct associations, summarise a disease's genes, drugs and phenotypes, and find simple one- or two-hop paths between two nodes. Results keep the relation labels, IDs and data provenance attached, and the skill warns that a path supports a hypothesis only.

• Find candidate nodes by name and choose the intended one
• List direct associations for a gene, drug, disease or phenotype
• Get a disease summary with associated genes, drugs, phenotypes and related diseases
• Find one- and two-hop association paths between two nodes

How do you install the primekg skill?

Download the skill ZIP from the skill page on this site and unzip it. The skill folder should contain SKILL.md, scripts/query_primekg.py and references/data-contract.md.

Put the folder in one of these locations, depending on how you want to use it. A personal install goes in ~/.claude/skills/. A project install goes in the .claude/skills/ folder of that project. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

How do you get the PrimeKG data file?

The helper does not query the internet for graph data. It reads a PrimeKG kg.csv file on your own machine, which is about 982 MB. Check that you have that much free disk space and several GB of free RAM before you start, because the helper loads the whole file for each query.

The source gives this download command as an illustration. It saves the file to kg.csv in the current folder and sets the PRIMEKG_DATA variable to its path. The helper reads PRIMEKG_DATA when it is imported. If the variable is not set, it looks for data/PrimeKG/kg.csv.

Before using the file, verify its checksum against the MD5 value listed in the skill's data reference, and record the DOI, file name, file ID and retrieval date with your results.

How do you trigger the skill with natural requests?

Ask for PrimeKG by name or describe a biological lookup. The skill is meant for requests about PrimeKG reproducibility, biological association lookup and hypothesis generation that needs traceable relations and sources. Name the entity type when you can, because the graph separates genes, drugs, diseases and phenotypes.

Expect the agent to show candidate matches before it runs a traversal, so you can choose the intended disease or drug yourself.

• Using PrimeKG, what genes are associated with Alzheimer disease?
• Which drugs have a recorded indication for this disease in PrimeKG?
• Find two-hop paths between this drug and this phenotype in the PrimeKG graph.
• Summarise the associated genes, drugs and phenotypes for this disease, with relation labels.

How do you read the results?

Each association carries a relation label. Read the label exactly, because it determines what the link means. For example, indication is a recorded drug-disease indication, while contraindication is a recorded contraindication and should never be counted as treatment support.

Phenotype links keep their sign. A disease_phenotype_negative record means the phenotype is recorded as absent, and a missing edge means unknown, not negative. Paths are undirected and show how the query walked the graph, which is not evidence of cause.

• indication: recorded drug-disease indication
• contraindication: recorded contraindication, not treatment support
• off-label use: kept separate from indication and contraindication
• disease_protein: disease-associated gene or protein
• disease_phenotype_positive and disease_phenotype_negative: recorded presence or absence
• effect/phenotype: the node type for phenotypes

What are the safety notes and limits?

The skill runs Python scripts and reads your local CSV. Network access is used only to fetch the public dataset file or its metadata. Query results are not clinical advice: the graph records associations, not treatment efficacy, prescribing decisions or diagnoses, and the skill states this.

The skill's listing shows an MIT licence, but the SKILL.md file in the source lists the license as Unknown, so check the repository before relying on a licence. The PrimeKG dataset record declares CC0 1.0, and its construction code is MIT. These are separate from the skill's own licence.

• Requires Python 3.11+ and pandas
• Needs a downloaded PrimeKG CSV and several GB of free RAM
• Do not use results for clinical or prescribing decisions
• The helper does not retrieve clinical text, publications, confidence scores or current approval status

What tips help you get reliable results?

Search is literal and case insensitive, and returns at most 20 matches unless you ask for all of them. Keep IDs as strings, including numeric-looking ones. Do not invent identifiers from labels, because drug nodes use DrugBank IDs and diseases use MONDO IDs.

If you query many times or have limited RAM, the source recommends building an indexed local store from the pinned file. Only PrimeKG CSVs are supported. Upstream PrimeKG now recommends OptimusKG for new work.

• Record the DOI, file name, file ID, checksum and retrieval date with every result
• Pick the intended node from the candidate list before tracing associations
• Treat a path as a hypothesis to check against the original sources