Skip to content
opentrons-integration · scientific-agent-skills · Flowy
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
One skill from scientific-agent-skills .
$ npx -y skills add K-Dense-AI/scientific-agent-skills --skill opentrons-integration --agent claude-codeInstalls just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itself Claude auto-loads it when your prompt matches the work. You can call it Invoke it directly when you want it. Slash command /opentrons-integration👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
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 📦 Ships with scientific-agent-skills
</> SKILL.md
opentrons-integration.SKILL.md
---
name : opentrons-integration
description : 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.
license : Unknown
metadata : {"version": "1.0", "skill-author": "K-Dense Inc."}
---
# Opentrons Integration
## Overview
Opentrons is a Python-based lab automation platform for Flex and OT-2 robots. Write Protocol API v2 protocols for liquid handling, control hardware modules (heater-shaker, thermocycler), manage labware, for automated pipetting workflows.
## When to Use This Skill
This skill should be used when:
- Writing Opentrons Protocol API v2 protocols in Python
- Automating liquid handling workflows on Flex or OT-2 robots
- Controlling hardware modules (temperature, magnetic, heater-shaker, thermocycler)
- Setting up labware configurations and deck layouts
- Implementing complex pipetting operations (serial dilutions, plate replication, PCR setup)
- Managing tip usage and optimizing protocol efficiency
- Working with multi-channel pipettes for 96-well plate operations
- Simulating and testing protocols before robot execution
Flowy AI Flows that just work. Hand-picked Claude Code plugins that fire the right skill as you prompt.
## Core Capabilities
### 1. Protocol Structure and Metadata
Every Opentrons protocol follows a standard structure:
```python
from opentrons import protocol_api
# Metadata
metadata = {
'protocolName': 'My Protocol',
'author': 'Name <email@example.com>',
'description': 'Protocol description',
'apiLevel': '2.19' # Use latest available API version
}
# Requirements (optional)
requirements = {
'robotType': 'Flex', # or 'OT-2'
'apiLevel': '2.19'
}
# Run function
def run(protocol: protocol_api.ProtocolContext):
# Protocol commands go here
pass
```
**Key elements:**
- Import `protocol_api` from `opentrons`
- Define `metadata` dict with protocolName, author, description, apiLevel
- Optional `requirements` dict for robot type and API version
- Implement `run()` function receiving `ProtocolContext` as parameter
- All protocol logic goes inside the `run()` function
### 2. Loading Hardware
**Loading Instruments (Pipettes):**
```python
def run(protocol: protocol_api.ProtocolContext):
# Load pipette on specific mount
left_pipette = protocol.load_instrument(
'p1000_single_flex', # Instrument name
'left', # Mount: 'left' or 'right'
tip_racks=[tip_rack] # List of tip rack labware objects
)
```
Common pipette names:
- Flex: `p50_single_flex`, `p1000_single_flex`, `p50_multi_flex`, `p1000_multi_flex`
- OT-2: `p20_single_gen2`, `p300_single_gen2`, `p1000_single_gen2`, `p20_multi_gen2`, `p300_multi_gen2`
**Loading Labware:**
```python
# Load labware directly on deck
plate = protocol.load_labware(
'corning_96_wellplate_360ul_flat', # Labware API name
'D1', # Deck slot (Flex: A1-D3, OT-2: 1-11)
label='Sample Plate' # Optional display label
)
# Load tip rack
tip_rack = protocol.load_labware('opentrons_flex_96_tiprack_1000ul', 'C1')
# Load labware on adapter
adapter = protocol.load_adapter('opentrons_flex_96_tiprack_adapter', 'B1')
tips = adapter.load_labware('opentrons_flex_96_tiprack_200ul')
```
**Loading Modules:**
```python
# Temperature module
temp_module = protocol.load_module('temperature module gen2', 'D3')
temp_plate = temp_module.load_labware('corning_96_wellplate_360ul_flat')
# Magnetic module
mag_module = protocol.load_module('magnetic module gen2', 'C2')
mag_plate = mag_module.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')
# Heater-Shaker module
hs_module = protocol.load_module('heaterShakerModuleV1', 'D1')
hs_plate = hs_module.load_labware('corning_96_wellplate_360ul_flat')
# Thermocycler module (takes up specific slots automatically)
tc_module = protocol.load_module('thermocyclerModuleV2')
tc_plate = tc_module.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')
```
### 3. Liquid Handling Operations
**Basic Operations:**
```python
# Pick up tip
pipette.pick_up_tip()
# Aspirate (draw liquid in)
pipette.aspirate(
volume=100, # Volume in µL
location=source['A1'] # Well or location object
)
# Dispense (expel liquid)
pipette.dispense(
volume=100,
location=dest['B1']
)
# Drop tip
pipette.drop_tip()
# Return tip to rack
pipette.return_tip()
```
**Complex Operations:**
```python
# Transfer (combines pick_up, aspirate, dispense, drop_tip)
pipette.transfer(
volume=100,
source=source_plate['A1'],
dest=dest_plate['B1'],
new_tip='always' # 'always', 'once', or 'never'
)
# Distribute (one source to multiple destinations)
pipette.distribute(
volume=50,
source=reservoir['A1'],
dest=[plate['A1'], plate['A2'], plate['A3']],
new_tip='once'
)
# Consolidate (multiple sources to one destination)
pipette.consolidate(
volume=50,
source=[plate['A1'], plate['A2'], plate['A3']],
dest=reservoir['A1'],
new_tip='once'
)
```
**Advanced Techniques:**
```python
# Mix (aspirate and dispense in same location)
pipette.mix(
repetitions=3,
volume=50,
location=plate['A1']
)
# Air gap (prevent dripping)
pipette.aspirate(100, source['A1'])
pipette.air_gap(20) # 20µL air gap
pipette.dispense(120, dest['A1'])
# Blow out (expel remaining liquid)
pipette.blow_out(location=dest['A1'].top())
# Touch tip (remove droplets on tip exterior)
pipette.touch_tip(location=plate['A1'])
```
**Flow Rate Control:**
```python
# Set flow rates (µL/s)
pipette.flow_rate.aspirate = 150
pipette.flow_rate.dispense = 300
pipette.flow_rate.blow_out = 400
```
### 4. Accessing Wells and Locations
**Well Access Methods:**
```python
# By name
well_a1 = plate['A1']
# By index
first_well = plate.wells()[0]
# All wells
all_wells = plate.wells() # Returns list
# By rows
rows = plate.rows() # Returns list of lists
row_a = plate.rows()[0] # All wells in row A
# By columns
columns = plate.columns() # Returns list of lists
column_1 = plate.columns()[0] # All wells in column 1
# Wells by name (dictionary)
wells_dict = plate.wells_by_name() # {'A1': Well, 'A2': Well, ...}
```
**Location Methods:**
```python
# Top of well (default: 1mm below top)
pipette.aspirate(100, well.top())
pipette.aspirate(100, well.top(z=5)) # 5mm above top
# Bottom of well (default: 1mm above bottom)
pipette.aspirate(100, well.bottom())
pipette.aspirate(100, well.bottom(z=2)) # 2mm above bottom
# Center of well
pipette.aspirate(100, well.center())
```
### 5. Hardware Module Control
**Temperature Module:**
```python
# Set temperature
temp_module.set_temperature(celsius=4)
# Wait for temperature
temp_module.await_temperature(celsius=4)
# Deactivate
temp_module.deactivate()
# Check status
current_temp = temp_module.temperature # Current temperature
target_temp = temp_module.target # Target temperature
```
**Magnetic Module:**
```python
# Engage (raise magnets)
mag_module.engage(height_from_base=10) # mm from labware base
# Disengage (lower magnets)
mag_module.disengage()
# Check status
is_engaged = mag_module.status # 'engaged' or 'disengaged'
```
**Heater-Shaker Module:**
```python
# Set temperature
hs_module.set_target_temperature(celsius=37)
# Wait for temperature
hs_module.wait_for_temperature()
# Set shake speed
hs_module.set_and_wait_for_shake_speed(rpm=500)
# Close labware latch
hs_module.close_labware_latch()
# Open labware latch
hs_module.open_labware_latch()
# Deactivate heater
hs_module.deactivate_heater()
# Deactivate shaker
hs_module.deactivate_shaker()
```
**Thermocycler Module:**
```python
# Open lid
tc_module.open_lid()
# Close lid
tc_module.close_lid()
# Set lid temperature
tc_module.set_lid_temperature(celsius=105)
# Set block temperature
tc_module.set_block_temperature(
temperature=95,
hold_time_seconds=30,
hold_time_minutes=0.5,
block_max_volume=50 # µL per well
)
# Execute profile (PCR cycling)
profile = [
{'temperature': 95, 'hold_time_seconds': 30},
{'temperature': 57, 'hold_time_seconds': 30},
{'temperature': 72, 'hold_time_seconds': 60}
]
tc_module.execute_profile(
steps=profile,
repetitions=30,
block_max_volume=50
)
# Deactivate
tc_module.deactivate_lid()
tc_module.deactivate_block()
```
**Absorbance Plate Reader:**
```python
# Initialize and read
result = plate_reader.read(wavelengths=[450, 650])
# Access readings
absorbance_data = result # Dict with wavelength keys
```
### 6. Liquid Tracking and Labeling
**Define Liquids:**
```python
# Define liquid types
water = protocol.define_liquid(
name='Water',
description='Ultrapure water',
display_color='#0000FF' # Hex color code
)
sample = protocol.define_liquid(
name='Sample',
description='Cell lysate sample',
display_color='#FF0000'
)
```
**Load Liquids into Wells:**
```python
# Load liquid into specific wells
reservoir['A1'].load_liquid(liquid=water, volume=50000) # µL
plate['A1'].load_liquid(liquid=sample, volume=100)
# Mark wells as empty
plate['B1'].load_empty()
```
### 7. Protocol Control and Utilities
**Execution Control:**
```python
# Pause protocol
protocol.pause(msg='Replace tip box and resume')
# Delay
protocol.delay(seconds=60)
protocol.delay(minutes=5)
# Comment (appears in logs)
protocol.comment('Starting serial dilution')
# Home robot
protocol.home()
```
**Conditional Logic:**
```python
# Check if simulating
if protocol.is_simulating():
protocol.comment('Running in simulation mode')
else:
protocol.comment('Running on actual robot')
```
**Rail Lights (Flex only):**
```python
# Turn lights on
protocol.set_rail_lights(on=True)
# Turn lights off
protocol.set_rail_lights(on=False)
```
### 8. Multi-Channel and 8-Channel Pipetting
When using multi-channel pipettes:
```python
# Load 8-channel pipette
multi_pipette = protocol.load_instrument(
'p300_multi_gen2',
'left',
tip_racks=[tips]
)
# Access entire column with single well reference
multi_pipette.transfer(
volume=100,
source=source_plate['A1'], # Accesses entire column 1
dest=dest_plate['A1'] # Dispenses to entire column 1
)
# Use rows() for row-wise operations
for row in plate.rows():
multi_pipette.transfer(100, reservoir['A1'], row[0])
```
### 9. Common Protocol Patterns
**Serial Dilution:**
```python
def run(protocol: protocol_api.ProtocolContext):
# Load labware
tips = protocol.load_labware('opentrons_flex_96_tiprack_200ul', 'D1')
reservoir = protocol.load_labware('nest_12_reservoir_15ml', 'D2')
plate = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D3')
# Load pipette
p300 = protocol.load_instrument('p300_single_flex', 'left', tip_racks=[tips])
# Add diluent to all wells except first
p300.transfer(100, reservoir['A1'], plate.rows()[0][1:])
# Serial dilution across row
p300.transfer(
100,
plate.rows()[0][:11], # Source: wells 0-10
plate.rows()[0][1:], # Dest: wells 1-11
mix_after=(3, 50), # Mix 3x with 50µL after dispense
new_tip='always'
)
```
**Plate Replication:**
```python
def run(protocol: protocol_api.ProtocolContext):
# Load labware
tips = protocol.load_labware('opentrons_flex_96_tiprack_1000ul', 'C1')
source = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D1')
dest = protocol.load_labware('corning_96_wellplate_360ul_flat', 'D2')
# Load pipette
p1000 = protocol.load_instrument('p1000_single_flex', 'left', tip_racks=[tips])
# Transfer from all wells in source to dest
p1000.transfer(
100,
source.wells(),
dest.wells(),
new_tip='always'
)
```
**PCR Setup:**
```python
def run(protocol: protocol_api.ProtocolContext):
# Load thermocycler
tc_mod = protocol.load_module('thermocyclerModuleV2')
tc_plate = tc_mod.load_labware('nest_96_wellplate_100ul_pcr_full_skirt')
# Load tips and reagents
tips = protocol.load_labware('opentrons_flex_96_tiprack_200ul', 'C1')
reagents = protocol.load_labware('opentrons_24_tuberack_nest_1.5ml_snapcap', 'D1')
# Load pipette
p300 = protocol.load_instrument('p300_single_flex', 'left', tip_racks=[tips])
# Open thermocycler lid
tc_mod.open_lid()
# Distribute master mix
p300.distribute(
20,
reagents['A1'],
tc_plate.wells(),
new_tip='once'
)
# Add samples (example for first 8 wells)
for i, well in enumerate(tc_plate.wells()[:8]):
p300.transfer(5, reagents.wells()[i+1], well, new_tip='always')
# Run PCR
tc_mod.close_lid()
tc_mod.set_lid_temperature(105)
# PCR profile
tc_mod.set_block_temperature(95, hold_time_seconds=180)
profile = [
{'temperature': 95, 'hold_time_seconds': 15},
{'temperature': 60, 'hold_time_seconds': 30},
{'temperature': 72, 'hold_time_seconds': 30}
]
tc_mod.execute_profile(steps=profile, repetitions=35, block_max_volume=25)
tc_mod.set_block_temperature(72, hold_time_minutes=5)
tc_mod.set_block_temperature(4)
tc_mod.deactivate_lid()
tc_mod.open_lid()
```
## Best Practices
1. **Always specify API level**: Use the latest stable API version in metadata
2. **Use meaningful labels**: Label labware for easier identification in logs
3. **Check tip availability**: Ensure sufficient tips for protocol completion
4. **Add comments**: Use `protocol.comment()` for debugging and logging
5. **Simulate first**: Always test protocols in simulation before running on robot
6. **Handle errors gracefully**: Add pauses for manual intervention when needed
7. **Consider timing**: Use delays when protocols require incubation periods
8. **Track liquids**: Use liquid tracking for better setup validation
9. **Optimize tip usage**: Use `new_tip='once'` when appropriate to save tips
10. **Control flow rates**: Adjust flow rates for viscous or volatile liquids
## Troubleshooting
**Common Issues:**
- **Out of tips**: Verify tip rack capacity matches protocol requirements
- **Labware collisions**: Check deck layout for spatial conflicts
- **Volume errors**: Ensure volumes don't exceed well or pipette capacities
- **Module not responding**: Verify module is properly connected and firmware is updated
- **Inaccurate volumes**: Calibrate pipettes and check for air bubbles
- **Protocol fails in simulation**: Check API version compatibility and labware definitions
## Resources
For detailed API documentation, see `references/api_reference.md` in this skill directory.
For example protocol templates, see `scripts/` directory.
© 2026 Flowy · Free and open source
Built for Claude Code · Not affiliated with Anthropic
