Skip to content
Get packs

Guide · Agent skill

How to use the Opentrons Lab Robot Protocols agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains the opentrons-integration agent skill, a set of instructions and templates that teaches an AI agent to write and check Python protocols for Opentrons Flex and OT-2 lab robots. An agent skill is a folder of instructions and files that an AI assistant loads when a request matches its description. By the end you will know what the skill does, how to install it, how to phrase requests that trigger it, and which safety steps must happen before any protocol touches a real robot.

Opentrons Lab Robot ProtocolsK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download the ZIP. Get the opentrons-integration skill ZIP from the K-Dense-AI scientific-agent-skills page for this item.
  2. 2Unzip into a skills folder. Place the opentrons-integration folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder.
  3. 3Install Python tools. Make sure Python 3.10 or newer and uv are installed on your computer.
  4. 4Ask for a protocol in plain language. Describe the robot, liquids, labware and steps you need, and mention Flex or OT-2.
  5. 5Simulate the protocol. Ask the agent to run the local simulation with the pinned opentrons package for your robot line.
  6. 6Review before any robot run. Import the file into the Opentrons App, pass analysis, and have a trained operator complete the dry run and safety checks.

What does the opentrons-integration skill make the agent do?

The skill covers writing, reviewing, migrating, simulating and troubleshooting Python protocols written with the official Opentrons Python Protocol API v2. These protocols tell a robot how to move liquids between plates and tubes, which labware, pipettes and modules to load, and how to set up the deck.

With the skill loaded, the agent follows the Protocol API rules for Flex and OT-2, picks labware and pipettes using the API load names, uses runtime parameters where a protocol needs user-adjustable settings, and simulates the protocol locally before any physical run. It also includes reference notes for liquid handling, modules and deck, and migrating older protocols.

  • Author new liquid-handling protocols for Flex or OT-2.
  • Review or troubleshoot an existing protocol before a run.
  • Migrate older OT-2 or Flex scripts to newer API levels.
  • Explain which API level supports a given feature.
  • Start from bundled templates: basic protocol, OT-2 basic protocol, PCR setup, absorbance reader and runtime parameters.

How do you install the skill?

Download the skill ZIP from the K-Dense-AI scientific-agent-skills page for this item, then unzip it. For a personal install, place the opentrons-integration folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

In the Claude apps you can instead upload the ZIP under Settings, then Capabilities, then Skills. The skill is MIT licensed, as stated in its SKILL.md file.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills → upload the ZIP

Which requirements do you need before using it?

Local simulation needs Python 3.10 or newer and uv, a Python package runner. The skill runs scripts and uses the network, because the uv command fetches the opentrons Python package when it runs. Physical execution additionally needs an Opentrons App and a compatible robot, but simulation does not.

The skill pins different opentrons packages for each robot line: one for Flex simulation and one for OT-2 compatibility checks. Requirements files for each line are included in the skill folder.

  • Python 3.10 or newer
  • uv (Python package runner)
  • opentrons Python package, pinned per robot line
  • Opentrons App and compatible robot, only for physical runs

How do you trigger the skill with a natural request?

You do not need to name the skill. The skill description covers requests about robot-specific liquid handling, deck and labware setup, pipettes, modules, runtime parameters, liquid classes and Opentrons App analysis. Describe the robot, the liquids and the steps you need, and mention Opentrons or Flex or OT-2 so the agent matches the right skill.

If you want a workflow that must work across several lab robot brands, say so. The skill itself says to use PyLabRobot instead in that case.

  • Write an Opentrons Flex protocol that transfers 100 µL from a reservoir to a 96-well plate, using a new tip each time.
  • Convert this OT-2 script to the current API level and tell me what changed.
  • Check this Opentrons protocol for labware, tip and volume problems before I import it into the App.
  • Add a runtime parameter that lets the operator choose the number of samples.

How do you simulate a protocol locally?

Simulation runs the protocol on your computer without a robot. The agent uses uv to run opentrons_simulate with a pinned package version. Use the Flex command for Flex protocols and the OT-2 command for OT-2 protocols. Simulation checks the Python protocol; Protocol Designer JSON files must be imported into the Opentrons App instead.

Simulation cannot verify physical calibration, liquid behaviour, meniscus position, labware tolerances or every possible collision. Treat a passing simulation as a necessary check, not a clearance to run.

  • Flex: use the pinned Flex opentrons package with opentrons_simulate.
  • OT-2: use the pinned OT-2 compatibility package with opentrons_simulate.
  • On Windows, run .venv-opentrons\Scripts\opentrons_simulate.exe after setting up a virtual environment.
uv run --no-project --isolated --python 3.12 --with "opentrons==10.0.0" opentrons_simulate protocol.py

What safety steps must you follow before a physical run?

The skill treats successful Python syntax or a clean simulation as no permission to run on a robot. Before live execution, import the protocol into the correct Opentrons App and require successful analysis. Then have an operator verify the robot model, software, pipettes, modules, labware, deck fixtures, tip count and volumes.

For new geometry, custom labware, partial tip pickup or gripper moves, the skill recommends a slow dry run with nonhazardous liquid. Keep the emergency stop accessible and follow your site's biosafety and chemical-safety rules. The templates are examples, not validated methods, so they do not replace a reviewed lab procedure.

  • Simulate with the same pinned package used for authoring.
  • Import into the correct Opentrons App and pass analysis.
  • Check the run preview and deck map with the operator.
  • Dry run with nonhazardous liquid when anything is new.
  • Keep the emergency stop within reach.

What tips help you get reliable results?

Give the agent the physical facts early: robot type, pipette model and mount, modules, exact labware load names, source and destination volumes, dead volume and tip policy. The skill says not to write final code until these are known. If something is uncertain, ask for a parameterized draft with a list of assumptions instead.

When you migrate a protocol, do not change only the API level string. Newer levels can change command validation and behaviour. Use the lowest API level that supports every feature the protocol needs.

  • Set one apiLevel only, in requirements, for Flex protocols.
  • Do not call load_trash_bin() on OT-2; it has a fixed trash.
  • Keep OT-2 protocols at the OT-2 API level limit; newer levels are Flex-only.
  • Ask the agent to list the API level each feature requires.

What people use it for

  • A lab automation engineer writes a Flex transfer protocol from a reservoir into a 96-well plate and checks it with local simulation.
  • A researcher migrates an older OT-2 script to the OT-2 API level and gets a list of changed commands.
  • A team reviews a colleague's protocol for missing tip racks, wrong labware names and volume problems before an operator imports it.
  • A group adds runtime parameters so an operator can choose the sample count on the robot screen.
  • A lab starts from the PCR setup or absorbance reader template and adapts it to its own deck layout.

Frequently asked questions

How do I install the opentrons agent skill?

Download the skill ZIP, unzip it, and place the opentrons-integration folder in ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps you can upload the ZIP under Settings, then Capabilities, then Skills.

Is the Opentrons agent skill free?

The skill is released under the MIT licence, as stated in its SKILL.md file. The page does not state pricing for the Opentrons software or robots, so check Opentrons directly for those costs.

What do I need to run the skill?

You need Python 3.10 or newer and uv for local simulation. Physical runs also need the Opentrons App and a compatible robot. The skill runs scripts and uses the network to fetch the opentrons package.

Can the skill control a robot directly?

The skill writes and checks protocol files and simulates them locally. A protocol must be imported into the Opentrons App and approved by an operator before it runs on hardware. The skill itself warns that simulation cannot confirm calibration, liquid behaviour or collisions.

What is the alternative if I use several lab robot brands?

The skill recommends PyLabRobot when one workflow must support multiple robot vendors. For no-code workflows on Opentrons, the skill points to Protocol Designer.

Why does my protocol fail analysis?

A common cause is an API level the robot does not support, or the same apiLevel set in both metadata and requirements. The skill advises setting apiLevel only in requirements and confirming the maximum supported level in the App's robot settings.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits lab automation engineers and researchers who write, migrate or review Opentrons Flex or OT-2 protocols and want an agent that follows the official API rules and simulates before running. It is not suited to running protocols on hardware without a trained operator, to multi-vendor workflows (use PyLabRobot), or to clinical or hazardous work without site biosafety review.

Download the skill