Skip to content
Get packs

Guide · Agent skill

How to use the Pathogen Variant Surveillance agent skill

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

The pathogen-variant-surveillance skill gives an AI agent a set of Python scripts that query public GenSpectrum and LAPIS sequence databases for lineage counts, weekly proportions, reporting delays and mutation frequencies. This guide explains what the skill does, how to install it, how to ask for it in plain language and how to read its output without overstating what the numbers mean.

Pathogen Variant SurveillanceK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Get the skill folder. Download the ZIP from the directory page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Check the requirements. Confirm you have Python 3.11 or newer and network access to the four public LAPIS and GitHub hosts listed in the skill.
  3. 3Ask a specific question. Name the pathogen, lineage or clade, place, and time window, for example US SARS-CoV-2 lineages over the last 12 weeks.
  4. 4Let the agent run the scripts. The agent chooses among reporting_lag.py, lineage_prevalence.py, resolve_lineage.py and mutation_profile.py depending on the question.
  5. 5Read the denominators and flags. Check the stated denominator, date window, snapshot details and any low-completeness flags before relying on a number.
  6. 6Verify lineage names. Use the resolver to confirm that names are current, withdrawn or aliased before describing them.

What does the skill make the agent do?

Without the skill, an agent answers questions about SARS-CoV-2 variants or H5N1 clades from memory, which can be out of date. With the skill installed, the agent fetches current counts from public GenSpectrum/LAPIS databases for the question it is asked. The skill covers SARS-CoV-2, influenza and H5N1 clades, RSV, mpox, measles, dengue and several other pathogens.

It produces weekly proportions with Wilson uncertainty intervals, checks whether lineage names are current, estimates how long submissions typically lag behind sample collection, and summarises common mutations. Its outputs describe counts of submitted sequences under stated filters. They are not case counts, infection prevalence or evidence of harm.

  • Weekly proportions of lineages in submitted sequences, with denominators and intervals
  • Checks of whether lineage names are current, withdrawn or aliased
  • Observed reporting delays between collection and submission or release
  • Descriptive site-wise mutation frequencies, optionally compared between two lineage groups

How do you install the skill?

Download the skill ZIP from the directory page. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. The folder you end up with should be named pathogen-variant-surveillance and contain SKILL.md, the scripts/ folder and the references/ folder.

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

  • Personal install: ~/.claude/skills/pathogen-variant-surveillance/
  • Project install: .claude/skills/pathogen-variant-surveillance/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the skill

How do you trigger the skill with a natural request?

You do not need to name the skill. The skill description lists the topics it covers, so requests that mention variant surveillance, Pango lineage validation, dominant submitted lineages, SARS-CoV-2, influenza or H5N1 clades, RSV, mpox, measles, dengue or LAPIS queries should bring it in. Ask about the specific pathogen, place and time window you care about, because the skill needs those to build a query.

Good requests say what you want counted and over what period. Vague requests such as 'what variants are around' will get a clarifying question or a broad answer with more caveats.

  • Which lineages appear most in US SARS-CoV-2 sequences submitted in the last 12 weeks, with confidence intervals?
  • Is the lineage name XFG still current in Pango, and what alias does it resolve to?
  • How long do US mpox sequence submissions usually take to appear after collection?
  • Which mutations in the S gene are more common in XFG* sequences than in XFJ* sequences since January 2026?

Run the scripts yourself

The agent normally runs the scripts for you. You can also run them yourself from the scripts folder. Each script prints its results with the filters and snapshot details used, so you can check what was counted. The skill works in four steps: inspect the database and choose filters, review reporting delays, discover and describe weekly proportions, then verify names and report counts with their denominators and exclusions.

To check reporting delays for US records over six monthly cohorts, skipping the three most recent months:

  • Use --where to set filters such as country=USA. Country field names differ between databases.
  • Use --top to ask for the most common exact lineage labels in a window.
  • Use --weeks to set how many ISO weeks to analyse.
  • Use --growth only when you need the descriptive log-odds slope; it is not a forecast.
  • Use --lag-days to exclude recent weeks that may still be incomplete. The 90-day value in the examples is an illustration, not a measured lag.
cd skills/pathogen-variant-surveillance/scripts python3 reporting_lag.py --where country=USA --cohorts 6 --skip-months 3 python3 lineage_prevalence.py --top 5 --where country=USA --weeks 12 python3 lineage_prevalence.py "XFG*" --where country=USA --weeks 16 --growth --lag-days 90 python3 resolve_lineage.py XFG PQ.17 PC.2 NOTALINEAGE --no-counts python3 mutation_profile.py "XFG*" --gene S --since 2026-01-01

How do you read the results without overstating them?

Every result is conditional on one database, the filters applied, the location, host, date window and the lineage assignment system used. Sequence databases reflect testing, specimen selection, sequencing, quality control and submission, so they are not a random sample of infections.

Treat weeks flagged as low as incomplete. Recent weeks, partial weeks and weeks with very few sequences are flagged. Lineage counts that include unassigned records keep those records in the denominator. Mutation frequencies with no coverage are unknown, not zero. Threshold labels such as above_both do not establish biological gain or loss.

  • Sequence prevalence is not infection prevalence.
  • A lineage with a successful count is not thereby an authoritative designation.
  • Reporting-delay results describe records visible now and do not prove that a week is complete.
  • A growth slope describes sampling change in the data, not transmissibility or fitness.

What does the skill need, and what should you know about safety?

The skill needs Python 3.11 or newer. Its scripts use only the Python standard library. It needs network access to lapis.cov-spectrum.org, lapis.genspectrum.org, lapis.pathoplexus.org and raw.githubusercontent.com, the last of which is used for Pango designation files. The public queries need no API keys or accounts.

The skill runs scripts and uses the network. Read SKILL.md and the scripts before you run them on a machine with sensitive data, and be aware that open access to a LAPIS endpoint is not a blanket data-use licence. Preserve source attribution and check the Pathoplexus terms of use where they apply.

  • Requires Python 3.11 or newer
  • Network access to four public hosts; no credentials needed for these queries
  • Runs local Python scripts and writes output as the agent directs
  • Does not run Nextclade, GenoFLU, authenticated APIs or sequence-level assay validation

Tips for getting reliable results

Ask for a specific pathogen, country and window. Inspect the actual category values before filtering, because a wrong country field or spelling can return zero. Give the lineage system explicitly when more than one naming system is in use, and do not sum overlapping descendant queries such as a parent label and its children.

  • Check exit codes: 1 means at least one name is withdrawn, unknown, unverified or failed to count; 2 means a required source or query failed.
  • Ask for the snapshot version, denominators and exclusions alongside any count you plan to publish.
  • Use --no-counts with the lineage resolver when you only need to check names.

What people use it for

  • Tracking which SARS-CoV-2 lineages make up the largest share of recently submitted sequences in a country, with weekly intervals
  • Checking whether a Pango lineage name is still current, and what it resolves to, before using it in a report
  • Estimating how long mpox or measles sequence submissions typically take to appear after collection in a chosen country
  • Comparing site-wise mutation frequencies in the S gene between two SARS-CoV-2 lineage groups
  • Summarising H5N1 or influenza clade counts in public submitted sequences for a teaching exercise

Frequently asked questions

How do I install the agent skill?

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

What does the pathogen variant surveillance skill require?

It requires Python 3.11 or newer and network access to lapis.cov-spectrum.org, lapis.genspectrum.org, lapis.pathoplexus.org and raw.githubusercontent.com. The scripts use only the standard library, and the public queries need no API keys or accounts.

Is the skill free and what is its licence?

The skill is licensed under MIT. The public queries it makes need no account or API key, but open access to an endpoint is not a blanket data-use licence, so keep source attribution and check the Pathoplexus terms where they apply.

Can it tell me whether a variant is more transmissible?

No. The skill describes sequence counts and proportions. Its growth fit is a descriptive log-odds slope on submitted sequences, and the skill states it is not a measure of transmissibility, fitness or a forecast.

Why does a lineage query return zero, or why is my lineage marked unverified?

Unknown or unindexed values can return zero, which does not prove the name is wrong or absent. An unindexed field without a naming authority stays unverified even when sequences carry that label. Check the category spelling in the database and use the resolver to confirm the name.

Does the skill replace Nextclade or assay validation?

No. The skill says it does not execute Nextclade, GenoFLU, authenticated APIs or sequence-level assay validation. Use those tools separately for sequence calling or assay work.

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, students and analysts who need current, sourced lineage counts from public sequence databases, with denominators and exclusions stated. It is not suited to clinical or public-health decisions, transmissibility or forecasting claims, or assay validation, and people needing those should choose other tools.

Download the skill