Agent skill

Protocol Verification

by Opentrons in Opentrons/opentrons

Simulate and analyze Opentrons protocols to verify correctness.

Apache-2.0Auto-check passedDevelopment

Install Protocol Verification

skills CLI
$ npx skills add Opentrons/opentrons --skill protocol-verification -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Opentrons/opentrons protocol-verification --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Opentrons/opentrons.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.cursor/skills/protocol-verification .claude/skills/protocol-verification && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
protocol-verification
GitHub stars
523
Token cost
~3k tokens
SKILL.md length
811 words
Files
1
Skills in repo
17
Repo updated
First seen
Licence
Apache-2.0

At a glance

Simulate and analyze Opentrons protocols to verify correctness.

  • Asked to verify
  • SKILL.md covers Prerequisites, Entry Points, Working Directories and Simulation, plus 5 more sections
  • Calls python, make and uv
  • Check a protocol

What it does

Protocol Verification is an agent skill from Opentrons/opentrons. Simulate and analyze Opentrons protocols to verify correctness. Use when asked to verify, simulate, analyze, validate, or check a protocol, or when needing to confirm a newly created protocol works.

Its SKILL.md is about 3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development. It works with Python. The repository describes itself as: Software for writing protocols and running them on the Opentrons Flex and Opentrons OT-2. The licence is Apache-2.0.

When your agent uses it

  • Asked to verify
  • Check a protocol
  • Needing to confirm a newly created protocol works

Example prompts

  • “/protocol-verification”

Requirements

  • Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit adb4970. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python
    • make
    • uv

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Protocol Verification loads about 3k tokens when it runs. Until then it costs about 55 tokens; SKILL.md has 811 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~55
When it runs · the whole SKILL.md, loaded when a task matches
~3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Opentrons/opentrons at commit adb4970, republished under its Apache-2.0 licence (© Opentrons). 811 words, ~2,967 tokens.

Download SKILL.mdSave it as .claude/skills/protocol-verification/SKILL.md (or your agent's skills folder).
name
protocol-verification
description
Simulate and analyze Opentrons protocols to verify correctness. Use when asked to verify, simulate, analyze, validate, or check a protocol, or when needing to confirm a newly created protocol works.

Protocol Verification — Simulate & Analyze

After creating or modifying a protocol, verify it using the binaries in api/.venv/bin/. All commands run from the monorepo root.

Prerequisites

The api/ venv must exist. If it doesn't (first time, or after teardown):

bash
make -C api setup

This creates api/.venv/ with all entry points installed. You only need to do this once.

OT-2 protocols (outside this repository's api/.venv)

OT-2 robot software and the Python API live in a separate fork (opentrons-ot2). This monorepo's api/ package (and api/.venv) is Flex-only: opentrons analyze and opentrons_simulate reject OT-2 protocols.

The same split applies on PyPI: opentrons==9.0.0 is the last release where one package could analyze or simulate both OT-2 and Flex. That wheel supports Python API through 2.28 (the last apiLevel shared across both robots before the fork). opentrons 9.1+ analyzes Flex only; use the OT-2 fork / OT-2 app stack for OT-2 protocols at 2.28 or below.

For mixed OT-2/Flex reference checks at apiLevel 2.28, create a separate Python 3.12 venv (do not commit it):

bash
uv venv /path/to/opentrons-9.0-venv --python 3.12
uv pip install --python /path/to/opentrons-9.0-venv/bin/python 'opentrons==9.0.0'

/path/to/opentrons-9.0-venv/bin/python -m opentrons.cli analyze tmp-protocols/my_protocol.py --check --json-output=-
/path/to/opentrons-9.0-venv/bin/opentrons_simulate tmp-protocols/my_protocol.py

Flex-only checks use api/.venv/bin/... from this monorepo (or current PyPI opentrons for Flex).

Entry Points

ToolBinaryNotes
Simulateapi/.venv/bin/opentrons_simulateFlex dev tree; OT-2 rejected
Analyzeapi/.venv/bin/python -m opentrons.cli analyzeFlex dev tree; OT-2 rejected
Simulate / analyze (OT-2 or mixed @ ≤2.28)Separate venv with opentrons==9.0.0 (see above)Last unified PyPI release; not monorepo api/.venv

Do not use uv run for one-off simulate/analyze calls. It checks and potentially rebuilds the venv on every invocation, adding significant latency. Call the venv binaries directly.

Working Directories

All local dev artifacts are gitignored and live at the monorepo root:

DirectoryPurpose
tmp-protocols/Protocol .py files
tmp-custom-labware/Custom labware .json definitions
tmp-csv/CSV files for RTP inputs

Simulation

Produces a human-readable runlog of every command the robot would execute. Use for quick validation.

⛔ RTP protocols cannot be simulated. opentrons_simulate has no --rtp-values or --rtp-files flag. If the protocol defines add_parameters() (any RTP — including CSV, int, bool, str, or float), you must tell the user this upfront and use opentrons analyze instead. Do not attempt to simulate an RTP protocol and let it fail; explain the limitation first, then switch to analyze automatically.

bash
# Standard
api/.venv/bin/opentrons_simulate tmp-protocols/my_protocol.py

# With custom labware (can be specified multiple times)
api/.venv/bin/opentrons_simulate tmp-protocols/my_protocol.py \
    -L tmp-custom-labware/

The current working directory is always searched for custom labware implicitly.

Simulation Options
FlagDescription
-l, --log-leveldebug, info, warning (default), error, none
-L, --custom-labware-pathDirectory to search for custom labware (repeatable)
-e, --estimate-durationEstimate protocol run time (experimental)
-o, --outputrunlog (default) or nothing
Interpreting Results
  • Success: runlog prints, exit code 0
  • Failure: Python traceback with error message, exit code 1

Common errors:

  • DeckConflictError — labware placement conflict
  • LabwareDefinitionDoesNotExist — invalid labware name
  • OutOfTipsError — not enough tips for the protocol
  • LiquidHeightUnknownError — .meniscus() called on a well without load_liquid() — see reference-source-map.md
  • IncompatibleAddressableAreaError — wrong slot for robot type

Analysis

Produces structured JSON with predicted commands, labware layout, pipettes, modules, and errors. Use for deep inspection or CI validation. Also the only way to verify protocols with CSV RTPs.

bash
# Standard
api/.venv/bin/python -m opentrons.cli analyze tmp-protocols/my_protocol.py \
    --check --human-json-output=-

# With custom labware — pass the JSON file(s) as extra positional arguments
api/.venv/bin/python -m opentrons.cli analyze \
    tmp-protocols/my_protocol.py \
    tmp-custom-labware/my_custom_plate.json \
    --check --json-output=-

# With primitive RTP values (int, float, bool, str)
api/.venv/bin/python -m opentrons.cli analyze tmp-protocols/my_protocol.py \
    --check --json-output=- \
    --rtp-values='{"sample_count": 8, "dry_run": false}'

# With CSV RTP file
api/.venv/bin/python -m opentrons.cli analyze tmp-protocols/my_protocol.py \
    --check --json-output=- \
    --rtp-files='{"transfer_map": "tmp-csv/transfer_map.csv"}'

# Combined: custom labware + CSV RTP
api/.venv/bin/python -m opentrons.cli analyze \
    tmp-protocols/my_protocol.py \
    tmp-custom-labware/my_custom_plate.json \
    --check --json-output=- \
    --rtp-files='{"transfer_map": "tmp-csv/transfer_map.csv"}'
Show full SKILL.md (336 more words)Show less
Analysis Options
FlagDescription
--json-output=FILEMachine-readable JSON (- for stdout)
--human-json-output=FILEPretty-printed JSON (- for stdout)
--checkExit non-zero if protocol has errors
--rtp-values=JSONPrimitive RTP values as JSON string (int, float, bool, str)
--rtp-files=JSONCSV RTP file paths as JSON string — keys are variable_names
--log-output=PATHLog destination (- stdout, stderr default, or file path)
--log-levelDEBUG, INFO, WARNING (default), ERROR

Custom labware in analyze: there is no -L flag. Pass each labware JSON as an extra positional file argument. The analyze command recognizes them by their JSON schema and registers them before running.

JSON Output Structure
json
{
  "createdAt": "...",
  "result": "ok",
  "robotType": "OT-3",
  "config": {"protocolType": "python", "apiVersion": [2, 28]},
  "metadata": {"protocolName": "..."},
  "commands": [...],
  "labware": [...],
  "pipettes": [...],
  "modules": [...],
  "liquids": [...],
  "errors": [],
  "runTimeParameters": [...]
}

Key fields: result ("ok" / "not-ok" / "parameter-value-required"), errors (empty = valid), commands (full ordered command list).

With Runtime Parameters
bash
api/.venv/bin/python -m opentrons.cli analyze protocol.py \
    --check --json-output=output.json \
    --rtp-values='{"sample_count": 48, "dry_run": false}'

# CSV parameter files
api/.venv/bin/python -m opentrons.cli analyze protocol.py \
    --check --json-output=output.json \
    --rtp-files='{"plate_map": "/path/to/map.csv"}'

Standard Verification Workflow

Before running anything, check whether the protocol defines add_parameters(). If it does, skip simulate entirely and go straight to analyze — then tell the user why.

bash
# 1. Quick check — simulate (only if protocol has NO add_parameters())
api/.venv/bin/opentrons_simulate tmp-protocols/my_protocol.py

# 1b. Quick check — simulate with custom labware (still no RTPs)
api/.venv/bin/opentrons_simulate tmp-protocols/my_protocol.py \
    -L tmp-custom-labware/

# 2. Deep check — analyze (required for any protocol with add_parameters())
api/.venv/bin/python -m opentrons.cli analyze \
    tmp-protocols/my_protocol.py \
    [tmp-custom-labware/my_plate.json] \
    --check --human-json-output=- \
    [--rtp-values='{"key": value}'] \
    [--rtp-files='{"csv_param": "tmp-csv/file.csv"}']

Decision guide:

ScenarioUseAgent behavior
No RTPs, no custom labwaresimulateRun simulate directly
Custom labware onlysimulate with -LRun simulate directly
Any RTP (add_parameters() present)analyze onlyTell the user: "opentrons_simulate cannot run RTP protocols — switching to opentrons analyze", then run analyze
Custom labware + any RTPanalyze with extra JSON argsSame — explain, then analyze

Snapshot Testing Integration

For Flex protocols to be tracked for regression, use analyses-snapshot-testing/ (Flex-only in this repository):

bash
cd analyses-snapshot-testing/

# Naming: {Robot}_{Status}_{Version}_{Pipettes}_{Modules}_{Description}.py
# Example: Flex_S_v2_28_P1000_GRIP_SerialDilution.py

make prep
make snapshot-test-update PROTOCOL_NAMES=Flex_S_v2_28_P1000_GRIP_SerialDilution OVERRIDE_PROTOCOL_NAMES=none

See the analyses-snapshot-testing skill for full details.

Keeping This Skill Current

When simulate or analyze surfaces a new error pattern, constraint, or CLI behavior that isn't already documented here, add it to the Troubleshooting section or update the relevant command example. The next person hitting the same issue will thank you.

Troubleshooting

api/.venv/ doesn't exist
bash
make -C api setup
Simulation succeeds but analysis shows errors

Analysis is stricter. Check the errors array in JSON output for details.

Protocol works in simulation but fails on robot

Simulation doesn't verify physical constraints: actual tip presence, liquid volumes, module calibration, or physical deck geometry.

Slow runs

If you accidentally used uv run instead of the venv binaries, it checks/rebuilds the venv each time. Switch to api/.venv/bin/... for instant invocations.

© Opentrons, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .cursor/skills/protocol-verification of Opentrons/opentrons.

Open the folder on GitHubat commit adb4970

Compare with similar skills

Protocol Verification next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Protocol Verification compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Protocol Verification this skillOpentrons/opentrons523—~3kAutomated safety check: PassApache-2.0
Code Review ChecklistshareAI-lab/learn-claude-code78k5 repos~1.1kAutomated safety check: PassMIT
Minimizing Ty Ecosystem Changesastral-sh/ruff50k—~4.6kAutomated safety check: PassMIT
Merge Dependabot PRsonyx-dot-app/onyx32k1 repos~2.2kAutomated safety check: PassMIT
Summarise Ecosystem Resultsastral-sh/ruff50k—~2.2kAutomated safety check: PassMIT
Senior Architect Toolkitmaslennikov-ig/claude-code-orchestrator-kit2608 repos~1.2kAutomated safety check: NotesCustom licence

Similar skills

  • Code Review Checklist

    shareAI-lab/learn-claude-code

    Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.

    78k GitHub starsUsed in 5 repos~1.1k tokens
    DevelopmentAuto-check passed
  • Official

    A skill your agent uses when a user says "minimize this ty ecosystem change", "reproduce this ecosystem result", "investigate a primer difference", "investigate a mypyprimer difference"…

    50k GitHub stars~4.6k tokensUpdated today
    DevelopmentAuto-check passed
  • Merge Dependabot PRs

    onyx-dot-app/onyx

    Triages and lands a batch of open Dependabot PRs in the Onyx repo, where main is gated exclusively by GitHub's merge queue: approves and enqueues green PRs, closes superseded duplicates, fixes…

    32k GitHub starsUsed in 1 repo~2.2k tokens
    DevelopmentAuto-check passed
  • Official

    A skill your agent uses when a user says "summarise ecosystem results", "summarize this ty ecosystem report", "what changed in this ecosystem run?", or asks to summarise or summarize ty ecosystem…

    50k GitHub stars~2.2k tokensUpdated today
    DevelopmentAuto-check passed
  • Senior Architect Toolkit

    maslennikov-ig/claude-code-orchestrator-kit

    Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin…

    260 GitHub starsUsed in 8 repos~1.2k tokens
    DevelopmentAuto-check: notes
  • Kedro Babysit

    kedro-org/kedro

    Run Kedro's local lint / format / type-check / tests on changed files (uses the project's pre-commit hooks, ruff, mypy, pytest, lint-imports, detect-secrets, Make targets — in the right venv), or…

    11k GitHub stars~4k tokensUpdated yesterday
    DevelopmentAuto-check passed

More from Opentrons/opentrons

All 17 skills in this repo
  • AI Client

    Opentrons/opentrons

    Conventions for the opentrons-ai-client React/TypeScript frontend — project structure, API integration, state management (Jotai), feature flags, types, and testing.

    523 GitHub stars~1.6k tokensUpdated today
    Auto-check passed
  • AI Server

    Opentrons/opentrons

    Conventions for the opentrons-ai-server FastAPI service — project structure, uv dependency management, settings, testing, Docker, and deployment.

    523 GitHub stars~2.5k tokensUpdated today
    Auto-check: notes
  • Analyses Snapshot Testing

    Opentrons/opentrons

    Conventions for the analyses snapshot testing framework in analyses-snapshot-testing/.

    523 GitHub stars~1.7k tokensUpdated today
    Auto-check passed
  • CSS Modules

    Opentrons/opentrons

    CSS Modules conventions, Stylelint rules, design tokens (spacing, colors, typography, border-radius), and patterns for the Opentrons monorepo.

    523 GitHub stars~2.2k tokensUpdated today
    Auto-check passed
  • Docs

    Opentrons/opentrons

    Authoring and styling guidelines for the Opentrons /docs MkDocs project.

    523 GitHub stars~2.8k tokensUpdated today
    Auto-check passed
  • E2E Testing

    Opentrons/opentrons

    E2E testing conventions for Protocol Designer and Labware Library using Playwright + pytest in e2e-testing/.

    523 GitHub stars~3k tokensUpdated today
    Auto-check: notes

Works with

Categories

Questions about Protocol Verification

What does Protocol Verification do?

Simulate and analyze Opentrons protocols to verify correctness. Protocol Verification is an agent skill from Opentrons/opentrons. Simulate and analyze Opentrons protocols to verify correctness.

When should I use Protocol Verification?

Protocol Verification fits situations like: asked to verify; check a protocol; needing to confirm a newly created protocol works.

How do I install Protocol Verification in Claude Code?

Run `npx skills add Opentrons/opentrons --skill protocol-verification -a claude-code`. Or copy the skill folder (.cursor/skills/protocol-verification in Opentrons/opentrons) into .claude/skills/protocol-verification in your project. Claude Code loads it when a task matches its description.

How do I install Protocol Verification in Codex?

Run `npx skills add Opentrons/opentrons --skill protocol-verification -a codex`. Or copy the skill folder (.cursor/skills/protocol-verification in Opentrons/opentrons) into .agents/skills/protocol-verification in your project. Codex loads it when a task matches its description.

Can I use Protocol Verification in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Opentrons/opentrons --skill protocol-verification -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/protocol-verification, .gemini/skills/protocol-verification, .github/skills/protocol-verification and .opencode/skills/protocol-verification in your project.

What does Protocol Verification need to run?

Going by SKILL.md and its folder, Protocol Verification needs the command-line tools its instructions call (python, make and uv). Our summary lists: Python 3.

Does Protocol Verification access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Protocol Verification safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Protocol Verification use?

Protocol Verification is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Protocol Verification use?

About 3k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Protocol Verification?

Skills that share tags, products or a category with Protocol Verification: Code Review Checklist (shareAI-lab/learn-claude-code, 78k stars), Minimizing Ty Ecosystem Changes (astral-sh/ruff, 50k stars), Merge Dependabot PRs (onyx-dot-app/onyx, 32k stars) and Summarise Ecosystem Results (astral-sh/ruff, 50k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Protocol Verification?

Opentrons (a GitHub organization) maintains it in Opentrons/opentrons, which has 523 GitHub stars. The repository holds 17 skills in this directory. The repository was last updated on October 8, 2026.

Source: Opentrons/opentrons on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.