How to use the PyLabRobot Lab Automation Planner agent skill

What the pylabrobot skill makes the agent do

Agent skills are folders of instructions that an AI assistant loads when a task matches them. The pylabrobot skill focuses on PyLabRobot, a hardware-agnostic Python library for lab automation. With it loaded, the agent can answer API questions, draft protocols, and review resource layouts and transfer tables.

The skill is built around offline work. The agent can validate a protocol manifest, check deck layout for simple overlaps, check transfer tables, and produce a JSON simulation plan using software-only backends. It uses the chatterbox backend, which prints planned operations and does not connect to hardware.

• Validate a protocol manifest against the included JSON schema.
• Check deck geometry using conservative static axis-aligned boxes (this is not a motion planner).
• Check transfer tables: one new tip per row, volumes, dead volume, tip capacity, wells, channels, heights, rates and units.
• Produce a JSON simulation plan using software-only backends.
• Inspect the installed PyLabRobot backends and confirm the expected version.

Install the pylabrobot skill

Download the ZIP of the skill from this page and unzip it. Then place the skill folder in one of these locations, depending on how you want to use it:

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal use: unzip into ~/.claude/skills/ so the skill is available across your projects.
• Single project: unzip into the project's .claude/skills/ folder so it applies only there.

Set up the offline Python environment

The bundled planning scripts need Python 3.11+. For offline API inspection and chatterbox simulation, the skill uses PyLabRobot 0.2.2 installed through uv. Run these commands from your project root to create the environment:

• Requires Python 3.9+ and PyLabRobot 0.2.2 for API inspection and chatterbox simulation.
• On Windows, use .venv-pylabrobot\Scripts\python.exe instead of the bin path.
• Do not install hardware extras such as serial or USB unless you have named the device and explicitly approved its transport dependencies.

Trigger the skill with natural requests

You do not need special syntax. Describe the task in plain language and mention PyLabRobot, liquid handling or deck layout. The agent will match the request to the skill when the task fits. Be specific about what you have, and expect the agent to ask for missing details rather than guess them.

The skill requires intake of details such as the exact device model, the deck and carriers, labware capacities, tip model, transfer units, and the contamination policy. If these are missing, the agent should give you an assumptions and blockers list and an offline draft only.

• "Review my PyLabRobot transfer table for dead volume and tip capacity problems."
• "Check whether the labware on my deck layout overlap in this PyLabRobot manifest."
• "Draft an offline PyLabRobot protocol plan for a 96-well plate transfer using the chatterbox backend."
• "Explain the difference between pick_up_tips and drop_tips in PyLabRobot 0.2.2."

Run the offline checks yourself

The skill runs from the repository root. Each bundled CLI uses strict, bounded UTF-8 JSON or CSV input, local paths, fixed allowlists, and JSON output. None of them can select a live backend. The fixtures below are synthetic examples shipped with the skill project, so point them at your own manifest once you have one.

• Validate the manifest with scripts/validate_manifest.py.
• Check geometry with scripts/check_deck_geometry.py.
• Review the transfer table with scripts/plan_transfers.py.
• Generate the simulation plan with scripts/generate_simulation_plan.py.
• Check the backends with scripts/inspect_backends.py --expected-version 0.2.2 --strict.

Understand the safety boundary

The skill is built to refuse to drive real hardware automatically. It will not connect to, initialize, home, move, heat, shake, spin, pump or otherwise command physical equipment. Changing an environment variable, config value or import does not turn a simulation into a live backend.

Any live run is a separate, human-authorized step. A trained operator must confirm the exact backend, device identity, deck, and protocol revision, reconcile the physical deck against the resource tree, verify calibration and clearances, and approve a slow dry run when anything is new or changed. Tracker state is bookkeeping, not sensing, so it cannot prove that liquid or a tip is physically present.

• Scripts make no serial, USB or network connections.
• The bundled CLIs need no network access.
• Chatterbox output shows planned operations; it does not prove calibration, reachability, collision freedom or liquid behaviour.
• The Visualizer renders resource and tracker events; it does not model physics.

Tips for getting useful results

Give the agent the real constraints before asking for a plan. Provide the labware capacities, dead volumes, initial volumes and units, because the skill will not guess them. Keep the offline draft separate from any hardware work, and treat the output as a review aid for a trained person rather than a finished protocol.

If a run fails on a real device, do not let anyone retry from the pre-error plan. The skill's guidance is to preserve the error and channel details and have the operator reconcile tips and volumes before resuming.

• Start from the synthetic fixtures and then replace them with your own manifest.
• Ask for an assumptions and blockers list whenever the input is incomplete.
• Review the reference files (liquid handling, deck resources, hardware backends, review) when you need detail on an API.