Official Opentrons Protocol API for OT-2 and Flex robots. Use when writing protocols specifically for Opentrons hardware with full access to Protocol API v2 features. Best for production Opentrons protocols, official API compatibility. For multi-vendor automation or broader equipment control use pylabrobot.
SKILL.md
Opentrons Integration
Overview
Create production-minded Python Protocol API v2 protocols for Opentrons Flex and
OT-2. This skill covers protocol structure, hardware and deck configuration,
liquid handling, runtime customization, module control, simulation, and safe
deployment.
The verified baseline as of 2026-07-23 is:
opentrons==9.1.1 for reproducible Flex simulation.
opentrons==9.0.0 for local OT-2 API 2.28 compatibility simulation.
Flex supports API levels 2.15 through 2.29 on current software.
OT-2 supports API levels 2.0 through 2.28 on current software.
API 2.29 is Flex-only at this baseline. Do not put 2.29 in an OT-2 protocol.
Read references/sources.md for the upstream documentation used for this
snapshot. Recheck the official versioning page before targeting newer robot
software.
Safety Boundary
Opentrons protocols control physical equipment. Never treat successful Python
syntax or local simulation as permission to run on a robot.
Before live execution:
Simulate locally with the same pinned opentrons version used for authoring.
Import the protocol into the correct Opentrons App and require successful
analysis.
Verify robot model, software, pipettes, mounts, modules, adapters, labware
definitions, deck fixtures, tip count, source volumes, dead volumes, and
destination capacity.
Review the run preview and deck map with the operator.
Perform a slow dry run with nonhazardous liquid when geometry, custom
labware, partial tip pickup, or gripper moves are new.
Keep the emergency stop accessible and follow site-specific biosafety,
chemical-safety, and contamination-control procedures.
Simulation cannot verify physical calibration, liquid properties, meniscus
behavior, labware manufacturing tolerances, cap or seal removal, tubing, or all
possible collisions.
Choose the Right Interface
Use this skill for Python files imported into the Opentrons App and run through
the Protocol API.
Use Protocol Designer for supported no-code workflows.
Use PyLabRobot for a hardware-agnostic workflow spanning vendors.
Treat the robot's HTTP API as a separate integration surface. If direct HTTP
control is explicitly required, use the OpenAPI document served by the target
robot and do not infer endpoints from Protocol API methods.
Required Intake
Do not write final protocol code until these facts are known:
Robot: Flex or OT-2, plus installed robot software.
Pipette model, volume range, channel count, and mount.
Modules and generations; Flex Gripper or Stacker availability.
Exact labware API load names and custom definition files, if any.
Use requirements-ot2.txt instead for an OT-2 compatibility environment. On
Windows, invoke the executable from .venv\Scripts\opentrons_simulate.exe.
Local simulation is for Python protocols; import Protocol Designer JSON files
into the appropriate Opentrons App instead.
Protocol Skeletons
Flex, API 2.29
For Flex, requirements is mandatory. Put apiLevel only in requirements,
not in both metadata and requirements.
Use the lowest API level that provides every required feature when a protocol
must run across a mixed software fleet. Use the current maximum only when the
workflow needs its behavior or capabilities.
Authoring Workflow
1. Select robot and API level
Check the maximum supported API in the App under the robot's advanced settings.
Map every requested feature to its minimum API level using
references/api_reference.md.
Check that every requested volume is within the configured pipette and tip
range. A 100 nL operation is not an Opentrons pipetting task.
4. Choose a liquid-handling layer
Use aspirate(), dispense(), mix(), air_gap(), blow_out(), and
touch_tip() for explicit control.
Use transfer(), distribute(), and consolidate() for standard movements.
On Flex, consider transfer_with_liquid_class(),
distribute_with_liquid_class(), or consolidate_with_liquid_class() for
Opentrons-verified aqueous, volatile, or viscous behavior.
Use dynamic start/end locations or dynamic_mix() only when API 2.27+ and the
geometry has been reviewed.
Model contamination boundaries before optimizing tips. Never reuse a tip across
unrelated samples merely to reduce consumables. See
references/liquid_handling.md.
5. Add setup information and runtime controls
Use define_liquid() and labware-level load_liquid() or
load_liquid_by_well() to improve setup visualization. Do not use deprecated
Well.load_liquid() in new API 2.22+ protocols.
Define operator-controlled values in add_parameters() and read them from
protocol.params. Validate ranges and use defaults that produce a safe,
meaningful simulation. CSV parameters have no default and only one CSV
parameter can be selected per run.
6. Budget resources
Before simulation, calculate:
Tips or tip sets required under every branch.
Source volume = delivered volume + mixing loss + disposal volume + dead
volume + a justified reserve.
Maximum destination volume after every addition and mix.
Number of module, adapter, trash, and staging positions.
Incubation and module timing, including concurrent tasks.
7. Validate in layers
Compile: python -m py_compile protocol.py.
Simulate with the pinned package.
Inspect the run log for command count, tip changes, pauses, and unexpected
locations.
Import into the appropriate App and require successful analysis.
Perform an operator-reviewed dry run before first use.
See references/validation_and_operations.md.
Common Failure Modes
Using old names such as p300_single_flex; use current flex_* load names.
Declaring apiLevel in both metadata and requirements.
Using API 2.29 for OT-2.
Forgetting a Flex trash bin or waste chute.
Loading a Magnetic Module on Flex; use supported Flex magnetic hardware.
Calling read(wavelengths=...) on the plate reader; call initialize() first,
then read().
Using deprecated Well.load_liquid() instead of labware-level methods.
Assuming simulation verifies calibration, liquid height, or physical
clearances.
Passing an unsafe well to a partial-nozzle pipette, which can place tips
outside labware and cause a crash.
Using new_tip="once" across samples with incompatible contamination
requirements.
Bundled Templates
File
Purpose
scripts/basic_protocol_template.py
Minimal Flex 2.29 transfer with current names
scripts/ot2_basic_protocol_template.py
Minimal OT-2 2.28 transfer
scripts/serial_dilution_template.py
Full-plate 1:2 dilution with an 8-channel Flex pipette
scripts/pcr_setup_template.py
Flex PCR setup and Thermocycler cycling
scripts/runtime_parameters_template.py
Safe numeric and Boolean runtime parameters
scripts/absorbance_reader_template.py
Correct Flex plate-reader initialization and read workflow
Templates are starting points, not validated assays. Replace volumes, labware,
liquids, timing, and tip policies only after checking hardware compatibility and
the wet-lab method.
Reference Guide
Reference
Use it for
references/api_reference.md
Current load names, version gates, and high-value methods
references/protocol_authoring.md
Requirements, labware, runtime parameters, and design workflow
references/liquid_handling.md
Command selection, liquid classes, sensing, and partial tips
references/modules_and_deck.md
Module compatibility, deck fixtures, gripper, and Stacker
references/validation_and_operations.md
Simulation, App analysis, dry runs, and troubleshooting
references/migration-api-2-19-to-2-29.md
Updating older protocols and this skill's former patterns
