protocol-authoring

name: protocol-authoring description: Create valid Opentrons Python API protocols for OT-2 and Flex robots. Use when creating, writing, editing, or helping with protocol files, liquid handling automation, or Opentrons protocol development. Also use when debugging protocol errors to trace into API source code.

Opentrons Protocol Authoring

Behavior Defaults — READ FIRST

This skill is primarily used by developers, SDETs, and QA who need protocols for testing and development. Follow these defaults unless the user explicitly says otherwise:

1. Don't ask unnecessary questions. Pick reasonable labware, volumes, and pipettes. Just produce a valid, working protocol.
2. Keep protocols minimal. Use the fewest steps needed to demonstrate the requested behavior. Don't generate dozens of repeated transfers — 2–4 operations are enough to validate a feature.
3. Always define liquids with protocol.define_liquid() and well.load_liquid() for all source wells.
4. Default to liquid class functions (transfer_with_liquid_class, distribute_with_liquid_class, consolidate_with_liquid_class) on Flex with API >= 2.24. Fall back to plain transfer/distribute/consolidate only for OT-2 or when the user explicitly asks.
5. Default to Flex unless the user specifies OT-2.
6. Use the latest API version unless the user specifies otherwise. Look up MAX_SUPPORTED_VERSION in api/src/opentrons/protocols/api_support/definitions.py to get the current value.
7. Default liquid class: water. Use glycerol_50 or ethanol_80 if the protocol context calls for viscous or volatile liquids.
8. Reasonable defaults: flex_1channel_1000 pipette, opentrons_flex_96_tiprack_1000ul tip rack, nest_96_wellplate_2ml_deep plate, 100 µL transfer volume.

Quick Start — Flex Protocol (Default)

from opentrons import protocol_api

metadata = {
    "protocolName": "Liquid Class Transfer Demo",
    "author": "Opentrons",
    "description": "Minimal transfer using liquid classes",
}

requirements = {"robotType": "Flex", "apiLevel": "<MAX_SUPPORTED_VERSION>"}
# ^^^ Replace <MAX_SUPPORTED_VERSION> with the value from
# api/src/opentrons/protocols/api_support/definitions.py

def run(protocol: protocol_api.ProtocolContext) -> None:
    trash = protocol.load_trash_bin("A3")

    tiprack = protocol.load_labware("opentrons_flex_96_tiprack_1000ul", "D2")
    source_plate = protocol.load_labware("nest_96_wellplate_2ml_deep", "D1")
    dest_plate = protocol.load_labware("nest_96_wellplate_2ml_deep", "C1")

    pipette = protocol.load_instrument(
        "flex_1channel_1000", mount="left", tip_racks=[tiprack]
    )

    # Define and load liquids
    sample = protocol.define_liquid(
        name="Sample", description="Aqueous sample", display_color="#0088FF"
    )
    source_plate["A1"].load_liquid(liquid=sample, volume=500)
    source_plate["A2"].load_liquid(liquid=sample, volume=500)

    # Use liquid class transfer (default: water)
    water = protocol.get_liquid_class(name="water")
    pipette.transfer_with_liquid_class(
        liquid_class=water,
        volume=100,
        source=[source_plate["A1"], source_plate["A2"]],
        dest=[dest_plate["A1"], dest_plate["A2"]],
        new_tip="always",
    )

Quick Start — OT-2 Protocol

from opentrons import protocol_api

metadata = {
    "protocolName": "OT-2 Transfer Demo",
    "author": "Opentrons",
    "description": "Minimal transfer for OT-2",
}

requirements = {"robotType": "OT-2", "apiLevel": "<MAX_SUPPORTED_VERSION>"}

def run(protocol: protocol_api.ProtocolContext) -> None:
    tiprack = protocol.load_labware("opentrons_96_tiprack_300ul", "1")
    source_plate = protocol.load_labware("nest_96_wellplate_2ml_deep", "2")
    dest_plate = protocol.load_labware("nest_96_wellplate_2ml_deep", "3")

    pipette = protocol.load_instrument(
        "p300_single_gen2", mount="left", tip_racks=[tiprack]
    )

    sample = protocol.define_liquid(
        name="Sample", description="Aqueous sample", display_color="#0088FF"
    )
    source_plate["A1"].load_liquid(liquid=sample, volume=500)

    pipette.transfer(100, source_plate["A1"], dest_plate["A1"])

Required Elements

1. requirements dict — robotType ("Flex" or "OT-2") and apiLevel
2. def run(protocol): — entry point receiving ProtocolContext
3. Flex only: must load trash bin or waste chute before any drop_tip

metadata dict is optional but recommended. apiLevel goes in metadata OR requirements, not both.

Look up the current max API version from MAX_SUPPORTED_VERSION in api/src/opentrons/protocols/api_support/definitions.py. Flex requires >= 2.15.

Liquid Classes (Default for Flex)

Available liquid classes (Flex, API >= 2.24):

water = protocol.get_liquid_class(name="water")

# Transfer (1-to-1)
pipette.transfer_with_liquid_class(
    liquid_class=water, volume=100,
    source=[plate["A1"]], dest=[plate["B1"]],
    new_tip="always",
)

# Distribute (1-to-many)
pipette.distribute_with_liquid_class(
    liquid_class=water, volume=50,
    source=reservoir["A1"], dest=plate.rows()[0][:4],
    new_tip="once",
)

# Consolidate (many-to-1)
pipette.consolidate_with_liquid_class(
    liquid_class=water, volume=50,
    source=plate.rows()[0][:4], dest=reservoir["A1"],
    new_tip="once",
)

Defining Liquids (Always Do This)

sample = protocol.define_liquid(
    name="Sample", description="Aqueous sample", display_color="#0088FF"
)
buffer = protocol.define_liquid(
    name="Buffer", description="Wash buffer", display_color="#00CC66"
)
reagent = protocol.define_liquid(
    name="Reagent", description="Reaction reagent", display_color="#FF4444"
)

source_plate["A1"].load_liquid(liquid=sample, volume=500)
reservoir["A1"].load_liquid(liquid=buffer, volume=10000)

Common display colors: #0088FF (blue/sample), #00CC66 (green/buffer), #FF4444 (red/reagent), #FFB800 (yellow/media), #9933FF (purple/enzyme), #FF6B35 (orange/beads).

OT-2 vs Flex Key Differences

Flex Deck Layout

     1        2        3        4 (staging)
A  [ A1 ]  [ A2 ]  [ A3 ]  [ A4 ]
B  [ B1 ]  [ B2 ]  [ B3 ]  [ B4 ]
C  [ C1 ]  [ C2 ]  [ C3 ]  [ C4 ]
D  [ D1 ]  [ D2 ]  [ D3 ]  [ D4 ]

OT-2 Deck Layout

 10    11    12(trash)
  7     8     9
  4     5     6
  1     2     3

Pipettes

Flex

OT-2

Common Labware

Flex tip racks: opentrons_flex_96_tiprack_50ul, opentrons_flex_96_tiprack_200ul, opentrons_flex_96_tiprack_1000ul

OT-2 tip racks: opentrons_96_tiprack_20ul, opentrons_96_tiprack_300ul, opentrons_96_tiprack_1000ul

Plates: nest_96_wellplate_2ml_deep, corning_96_wellplate_360ul_flat, opentrons_96_wellplate_200ul_pcr_full_skirt, nest_96_wellplate_200ul_flat

Reservoirs: nest_12_reservoir_15ml, nest_1_reservoir_195ml, nest_1_reservoir_290ml

Tube racks: opentrons_24_tuberack_nest_1.5ml_snapcap, opentrons_6_tuberack_nest_50ml_conical

Modules Quick Reference

temp_mod = protocol.load_module("temperature module gen2", "D1")
tc = protocol.load_module("thermocycler module gen2")        # A1+B1 on Flex
hs = protocol.load_module("heaterShakerModuleV1", "C1")
mag_block = protocol.load_module("magneticBlockV1", "C1")    # Flex only
mag_mod = protocol.load_module("magnetic module gen2", "1")   # OT-2 only
apr = protocol.load_module("absorbanceReaderV1", "B3")        # Flex, API 2.21+
stacker = protocol.load_module("flexStackerModuleV1", "D4")   # Flex, API 2.25+

For detailed module operations, see reference-modules.md.

Runtime Parameters (API 2.18+)

def add_parameters(parameters: protocol_api.Parameters) -> None:
    parameters.add_int(variable_name="sample_count", display_name="Samples",
                       default=8, minimum=1, maximum=96)
    parameters.add_bool(variable_name="dry_run", display_name="Dry Run", default=False)

def run(protocol: protocol_api.ProtocolContext) -> None:
    count = protocol.params.sample_count

For complete RTP guide, see reference-rtp.md.

Working Directories (Monorepo Root)

All local dev artifacts live in these gitignored directories:

Custom Labware

Custom labware JSON files go in tmp-custom-labware/. The parameters.loadName in the JSON is the string passed to load_labware().

Creating a Custom Labware Definition

The easiest starting point is copying an existing definition from shared-data/labware/definitions/2/<name>/<version>.json and modifying the key fields:

{
  "namespace": "custom",
  "version": 1,
  "parameters": {
    "loadName": "my_custom_plate"
  },
  "metadata": {
    "displayName": "My Custom Plate"
  }
  ...
}

Required changes when deriving from an existing definition:

• parameters.loadName → your unique load name (no spaces, underscores OK)
• namespace → "custom" (must not be "opentrons")
• version → 1
• metadata.displayName → human-readable name

Save as tmp-custom-labware/<loadName>.json (file name convention matches loadName).

Using Custom Labware in a Protocol

plate = protocol.load_labware("my_custom_plate", "D1")

No special import needed — the CLI handles loading the definition at run time.

For a proper custom labware definition from scratch, use the Opentrons Labware Creator

CSV Runtime Parameters

CSV files go in tmp-csv/. They are used exclusively via the add_csv_file RTP type (API 2.20+).

Defining a CSV Parameter

def add_parameters(parameters: protocol_api.Parameters) -> None:
    parameters.add_csv_file(
        variable_name="transfer_map",
        display_name="Transfer Map",
        description="CSV with columns: source_well, dest_well, volume_ul",
    )

Using the CSV in run()

rows = protocol.params.transfer_map.parse_as_csv()
# rows is a list of lists; rows[0] is the header row
for row in rows[1:]:
    src, dst, vol = row[0].strip(), row[1].strip(), float(row[2].strip())
    pipette.transfer(vol, source[src], dest[dst])

Example CSV (tmp-csv/transfer_map.csv)

source_well,dest_well,volume_ul
A1,A1,100
A2,A2,150
A3,A3,75

Note: opentrons_simulate cannot accept RTP files. Protocols with CSV RTPs must be verified with opentrons analyze. See the protocol-verification skill.

Additional References

Skill Reference Files (in this directory)

AI Server Source Docs (read on demand)

Located in opentrons-ai-server/api/storage/docs/. Use reference-examples-index.md to decide which file to read. Do not read all of them — they total ~10,000 lines. Read only what the current task needs.

Keeping This Skill Current

Update this skill whenever you discover something new. These files are the team's shared knowledge base — stale information hurts everyone.

How to update: use the Write or StrReplace tools on the relevant skill file. Keep edits focused — fix only what changed. Don't rewrite sections that are still accurate.

Common Mistakes

• Forgetting load_trash_bin() on Flex
• Using OT-2 pipette names on Flex or vice versa
• Putting apiLevel in both metadata and requirements
• Using numeric slots on Flex or alpha on OT-2
• Exceeding pipette volume range
• Using transfer with new_tip="never" without calling pick_up_tip() first
• Forgetting to define_liquid / load_liquid for source wells
• Using plain transfer on Flex when transfer_with_liquid_class is available
• Calling apr.initialize() without apr.close_lid() first (APR lid must be closed before init)
• Passing only the top well (e.g. plate["A1"]) to 8-channel *_with_liquid_class — must pass full column or set group_wells=False
• Using f-strings or variable references in metadata dict — the parser requires static literals only (no f"...", no {var}, no function calls)
• Wrapping transfer() in a for loop over wells — transfer() handles iteration internally; pass lists instead
• Using 8-channel pipette with wells() instead of columns() — 8-channel picks up an entire column at once
• Not accounting for 8-channel tip math: one pick_up_tip() = 8 tips; a single 96-well rack supports only 12 column operations
• Loading a 96-channel pipette without adapter="opentrons_flex_96_tiprack_adapter" for full (ALL) tip pickup
• Using start="A1" for 96-channel COLUMN mode — always use start="A12" to avoid deck edge collision
• Placing a tube rack in a staging area slot (A4–D4) — gripper cannot safely move tube racks
• Loading the Heater-Shaker or Temperature Module in column 2 slots (A2, B2, C2, D2) — forbidden on Flex