primer-design – Design & UI skill for AI agents

Primer design and specificity

Produce candidate oligos in 5-prime-to-3-prime orientation, with the exact template,

chemistry, intended products, and search scope behind each conclusion. Calculate

sequence-dependent quantities with the supplied tools. A familiar gene name, good

Primer3 penalty, or a single BLAST alignment cannot establish primer specificity.

Choose the workflow

| Request | Start here |

| --- | --- |

| New genomic PCR or RT-qPCR pair | Define the assay and reference; design; assess thermodynamics; screen products. |

| Check an existing pair | Prepare pair TSV; assess both full oligos and annealing cores; screen with explicit intended coordinates. |

| Exon junction, transcript isoform, allele discrimination | Read [design-workflows.md](references/design-workflows.md); supply sequence annotation before imposing constraints. |

| Cloning/adaptor-tailed primers | Design annealing cores, append declared 5-prime tails, reassess full oligos, reconstruct the final product. |

| Multiplex panel | Enable --multiplex in both thermodynamics and specificity tools to assess oligo interactions and cross-pair products. |

| Degenerate, bisulfite, probe, or modified-base assay | Use the specialized workflow in [design-workflows.md](references/design-workflows.md); the bundled ordinary-DNA model is insufficient. |

The local tooling supports paired primers with unambiguous ACGT cores. Advanced assay

types have substantive design and validation guidance, but are not silently reduced

to ordinary PCR. This skill designs assays; expression normalization, experimental

diagnostic validation, and guide-RNA design are separate tasks.

Establish the assay contract

Obtain what changes the result; use explicit provisional assumptions for an exploratory

design, and identify them in the report:

• Purpose and template: genomic DNA, cDNA, plasmid, or another defined substrate;

target organism, accession with version, assembly/transcript release, strand,

desired isoforms, and product-size range. Name wanted and unwanted templates.

• Sequence evidence: local FASTA plus source/retrieval date and its SHA-256 hash.

A locus excerpt uses local coordinates; record its mapping to the full reference.

Include relevant paralogs, pseudogenes, alternate contigs, transcript isoforms,

vector backbone, and host sequence in the appropriate screen.

• Reaction conditions: polymerase/buffer, monovalent salt, total divalent salt,

total dNTP, and oligo concentrations. Primer3 uses mM for salts/dNTP and nM for DNA.

Record the initial reaction concentration separately from Primer3's effective

annealing-oligo concentration parameter. Engine defaults are assumptions.

• Constraints: target interval, allowed/excluded binding regions, junctions,

variant exclusions and their source, fixed primers, tails, or multiplex membership.

Do not guess exon boundaries or silently substitute another assembly.

• Definition of an acceptable result: relevant off-target references, amplicon

lengths, mismatch search limits, controls, and experimental validation appropriate

to the assay. There is no universal thermodynamic cutoff that validates all PCRs.

Use [input-contract.md](references/input-contract.md) for file schemas and coordinate

examples. Copy [assay-report-template.md](assets/assay-report-template.md) into the

analysis directory to collect evidence. Reference retrieval may be manual or through

an established sequence API; preserve accession/version and verify the returned

sequence. The supplied scripts use local files and do not submit sequences online.

Install and verify

Set SKILL_DIR to this skill's actual installed directory. Work in a separate analysis

directory so environments, reference databases, and results do not enter the skill.

uv venv --python 3.13 .venv-primer
uv pip install --python .venv-primer/bin/python -r "$SKILL_DIR/assets/requirements.txt"
.venv-primer/bin/python "$SKILL_DIR/scripts/design_primers.py" --help

Use the environment's Scripts/python.exe on Windows. The design/thermodynamic

examples target primer3-py 2.3.1, tested with Python 3.13. For the optional

BLAST engine, install NCBI BLAST+ from its official distribution and check:

blastn -version
makeblastdb -version

Local integration checks also exercise BLAST+ 2.17.0; other releases require checking

their output and search behavior before claiming equivalent coverage.

Read [sources.md](references/sources.md) when updating dependencies or API assumptions.

The scripts record engine versions and effective settings in their JSON reports.

1. Design candidates

For an initial functional demonstration, use the bundled synthetic sequence. It is

nonbiological example input, not an experimentally validated assay:

.venv-primer/bin/python "$SKILL_DIR/scripts/design_primers.py" \
  --template "$SKILL_DIR/assets/demo-template.fasta" \
  --preset qpcr --config "$SKILL_DIR/assets/qpcr-config.json" \
  --output design.json --pairs-out pairs.tsv --expected-out expected.tsv

For actual work, substitute the reviewed target FASTA and constraints. A multi-record

FASTA requires --record with its exact ID. The pcr preset requests 100–1000 bp;

qpcr requests 70–200 bp. Override these starting ranges in the configuration.

The example overrides its range to 90–180 bp and includes a specific target interval.

Multiple SEQUENCE_TARGET intervals are alternatives: Primer3 flanks at least one.

To require coverage of every interval, supply one enclosing target and verify the

returned product; separate assays require separate design runs.

The tool:

• Passes validated sequence_args and global_args to Primer3. Unsupported or

misspelled tags fail rather than silently changing the task.

• Converts ambiguous template positions to N and forbids ambiguous primer bases.

It does not interpret lowercase sequence as a repeat mask; use explicit exclusions.

• Optionally imports --mask-bed exclusions in the supplied template's coordinates.

Use BED intervals for variant/repeat masking only after validating the reference

mapping; it does not infer allele frequencies or convert arbitrary VCFs.

• Verifies returned forward and reverse sequences against the template and checks

product lengths. Primer3's right-primer position is converted into a half-open

binding interval; the reverse primer is already in ordering orientation.

• Optionally appends --forward-tail and --reverse-tail to cores. The design score

and core Tm do not include those tails; step 2 checks complete oligos.

Inspect engine_explanations when no candidates are found. Change a biologically

justified constraint and rerun; do not silently relax all constraints or return an

invented sequence. Preserve previous reports when comparing parameter choices.

expected.tsv describes intended products on the design template. If screening

another reference, map these coordinates to its exact record IDs and orientation.

A cDNA product cannot be relabeled as a genomic interval across introns.

2. Assess thermodynamics

Use the same chemistry as the design. The following explicit values match the

bundled design defaults; replace them together when the actual conditions differ:

.venv-primer/bin/python "$SKILL_DIR/scripts/check_thermodynamics.py" \
  --pairs pairs.tsv --mv-conc 50 --dv-conc 1.5 --dntp-conc 0.6 \
  --dna-conc 50 --temp-c 37 --output thermodynamics.json

The report contains core Tm, core and full-oligo hairpins/homodimers, full-oligo

heterodimers, self 3-prime end stability, and both directional inter-oligo 3-prime

end-stability calculations. Delta-G and

delta-H are reported in kcal/mol; delta-S in cal/(mol K). --temp-c controls the

temperature for delta-G, not a recommended PCR annealing temperature.

If design used different Tm/salt models, also set --tm-method and

--salt-corrections-method to match; see the mapping in the input contract.

For a panel, add --multiplex to examine all unordered oligo combinations, including

forward/forward and reverse/reverse between different pairs. Distinguish a panel to

be combined from alternative candidates that will be tested separately.

Read [thermodynamics.md](references/thermodynamics.md) before interpreting these

values. Full oligos longer than 60 bases are reported as unresolved; they are never

silently truncated. Modified bases and degenerate mixtures require a suitable model.

Thermodynamic predictions support ranking and experimental planning, not a blanket

claim of primer quality.

Nonfinite Tm or a Tm at/below absolute zero is rejected as a calculation/input

failure; such a result must not be ranked as an ordinary low-Tm primer.

3. Screen amplification products

Read [specificity.md](references/specificity.md) before making a specificity claim.

Search each primer on both strands and pair inward-facing binding sites. A binding

hit alone is not an amp

… (full content is in the download package)