Conserved Primer Design

Agent skill package for using the VirusPrimerPro website API to design conserved primers, prepare phylogeny-guided inputs, and assemble tNGS amplicon panel deliverables.

This repository intentionally contains only the reusable agent skill package. It does not include the VirusPrimerPro web application source code.

Purpose

Use this package when an AI coding agent needs to call the VirusPrimerPro Agent API instead of using the GUI. The agent can:

• request or use an API key;
• upload aligned FASTA, tree, annotation, or GenBank files;
• submit conserved_region, primer_site, and phylo_guide jobs;
• poll long-running jobs without holding a long HTTP connection;
• download result artifacts;
• prepare NCBI + MAFFT alignments;
• curate genotype/reference datasets;
• screen primer specificity;
• QC primers and tNGS panels;
• export wet-lab order sheets and validation reports.

Repository Layout

agentskill/
  SKILL.md                         # Main Codex-style skill entry
  references/                      # API and preparation references
  scripts/                         # Standard-library helper scripts
  skills/                          # Smaller task-specific skills
  testdata/                        # Small smoke-test fixtures
AGENTS.md                          # Generic agent instructions
CLAUDE.md                          # Claude Code instructions
.github/copilot-instructions.md    # GitHub Copilot / VS Code instruction entry
docs/client-compatibility.md       # Client setup notes

Quick Start

Set API credentials in the agent runtime:

export VPP_AGENT_BASE_URL="https://your-virusprimerpro-host.example"
export VPP_AGENT_API_KEY="vpp_live_<prefix>_<secret>"

Submit an aligned FASTA to the Agent API:

python agentskill/scripts/vpp_agent_api.py \
  --base-url "$VPP_AGENT_BASE_URL" \
  --api-key-env VPP_AGENT_API_KEY \
  submit \
  --mode primer_site \
  --msa aligned.fasta \
  --profile standard \
  --config-json '{"mode":"primer_site","target_coverage":0.95,"amplicon_min":100,"amplicon_max":400}' \
  --wait \
  --poll-interval 30 \
  --output-dir results

The API is asynchronous. For heavy jobs, submit first, then poll:

python agentskill/scripts/vpp_agent_api.py status --run-id run_...
python agentskill/scripts/vpp_agent_api.py artifacts --run-id run_... --output-dir results

Client Compatibility

Codex

Use agentskill/SKILL.md as the main skill entry. A Codex agent should load this skill when it needs to call VirusPrimerPro through /api/v1/agent/*.

Recommended usage:

git clone https://github.com/KevinSpringer1/conserved-primer-design.git
cd conserved-primer-design
python agentskill/scripts/vpp_agent_api.py --help

Claude Code

Open this repository in Claude Code. Claude Code should read CLAUDE.md and use the helper scripts instead of manually reconstructing upload, polling, or artifact-download logic.

VS Code / GitHub Copilot

The repository includes .github/copilot-instructions.md. Open the cloned repository in VS Code and ask Copilot or another coding agent to follow those instructions when calling the VirusPrimerPro API.

Generic Agents

Agents that support repository instructions should read AGENTS.md. Agents that support skill-style folders should use agentskill/SKILL.md plus the task-specific entries under agentskill/skills/.

Production Workflow

1. Curate genotype/subtype/clade definitions with citations.
2. Curate and deduplicate reference accessions.
3. Download genomes and build an MSA with MAFFT.
4. For phylo_guide, prepare a tree and annotation from curated groups.
5. Submit to the VirusPrimerPro Agent API.
6. Poll status until succeeded or failed.
7. Download artifacts.
8. Run primer wet-lab QC and specificity screening.
9. Design or balance tNGS panel pools.
10. Export wet-lab sheets and validation reports.

Smoke Tests

Run local tests without a live VirusPrimerPro server:

python -m py_compile agentskill/scripts/*.py

python agentskill/scripts/curate_references.py validate-taxonomy \
  --taxonomy-json agentskill/testdata/sample_taxonomy.json \
  --output /tmp/vpp_taxonomy_report.json

python agentskill/scripts/primer_panel_qc.py qc-primers \
  --primers agentskill/testdata/sample_primers.csv \
  --output /tmp/vpp_primer_qc.json \
  --fail-on-warn

python agentskill/scripts/advanced_phylogeny.py validate-tree \
  --msa agentskill/testdata/sample_alignment.fasta \
  --tree agentskill/testdata/sample_tree.newick \
  --output /tmp/vpp_tree_validation.json

Security

• Do not commit API keys.
• Prefer VPP_AGENT_API_KEY and VPP_AGENT_ADMIN_TOKEN environment variables.
• Use short polling requests for long computations.
• Review all accession, specificity, primer QC, and panel reports before ordering primers.

License

MIT License. See LICENSE.