Guide · Agent skill

How to use the OMERO Microscopy Integration agent skill

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

The omero-integration skill gives an AI agent a structured, cautious way to work with OMERO, a server platform that stores and organises scientific microscope images. It is for lab data managers, bioimaging researchers and developers who need a scoped view of what is on an OMERO server. After this guide you will know what the skill does, how to install it, how to ask for work in plain language, and which safety limits apply.

OMERO Microscopy IntegrationK-Dense-AI/scientific-agent-skills · MIT Download the skill

Quick start

1Download the ZIP. Download the omero-integration skill ZIP from this page.
2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project.
3Or upload it in the Claude apps. Open Settings, then Capabilities, then Skills, and upload the ZIP.
4Prepare Python and omero-py. Use Python 3.10 or newer, ideally 3.12, and install the matching IcePy wheel and the pinned omero-py client.
5Set OMERO_ variables. Export OMERO_HOST and your credentials through your environment or secret manager, never on a command line.
6Ask for a scoped task. Name the group, object type, IDs and result limit, then review the dry-run output before approving any execution.

What is an agent skill, and what does this one do?

An agent skill is a folder of instructions and helper scripts that an AI agent loads when a task matches its description. This skill covers OMERO.server workflows using the omero-py Python client and the OMERO command line.

Once installed, the agent can produce bounded inventories of projects, datasets and images, export annotations and ROI shape geometry for specific image IDs to JSON, and build local import/export plans. Writes such as uploads, annotations or deletions are meant to happen only after you name an explicit, reviewed target.

The skill focuses on data access and metadata. It is not a general image-analysis tool and does not analyse pixels.

Scoped OMERO inventory of projects, datasets and images
Metadata and annotation export for named image IDs
ROI shape geometry export to JSON
Local import/export planning
Reviewed write workflows with an exact target

Install the omero-integration skill

Download the skill ZIP from this page and unzip it into one of these locations: ~/.claude/skills/ for personal use, or .claude/skills/ inside a project if only that project should use it.

If you use the Claude apps instead, open Settings, then Capabilities, then Skills, and upload the ZIP there.

The skill needs Python 3.10 or newer, with 3.12 recommended. If you prepare a local client environment, the skill's own instructions use uv to create a Python 3.12 virtual environment. Installing the client also requires a ZeroC IcePy wheel that matches your Python version, operating system and architecture, which the skill tells you to download from the official OMERO-linked matrix rather than compile.

Python 3.10 or newer (3.12 recommended)
omero-py, the pinned OMERO.py client listed in the skill
ZeroC IcePy wheel matching your interpreter and platform
Network access to an OMERO.server you are authorised to use

uv venv --python 3.12 .venv
source .venv/bin/activate

Set up credentials safely

The skill reads credentials only from named OMERO_ variables in your environment or secret manager. It does not search parent directories or load .env files. Passwords and session keys should never appear in command arguments, code, output or chat.

OMERO_HOST is required. OMERO_PORT defaults to 4064, OMERO_SECURE defaults to true, and you supply either OMERO_USER with OMERO_PASSWORD, or OMERO_SESSION_KEY. A session key is a bearer credential, so treat it like a password.

OMERO_HOST: the server hostname (required)
OMERO_PORT: SSL router port, default 4064
OMERO_USER and OMERO_PASSWORD, or OMERO_SESSION_KEY
OMERO_SECURE: secure transport toggle, default true

export OMERO_HOST="omero.example.org"
export OMERO_PORT="4064"
export OMERO_USER="researcher"
export OMERO_SECURE="true"

Trigger the skill with natural requests

You do not need special syntax. Describe the OMERO task and name the scope. The agent is instructed to start with local validation or a dry run and will not connect until you have chosen the host, group, object type, IDs and result limit.

Be specific about what you want exported or listed and how many items you accept. Vague requests such as 'export everything' are not what the skill is built for.

'Inventory the first 25 images in Project 12 on our OMERO server, IDs only.'
'Export annotations for image IDs 101, 102 and 103 to JSON.'
'Plan an import of the folder in my local staging directory, but do not upload anything.'
'Export ROI shape geometry for image 205, limited to 50 shapes.'

Understand the safety limits and bundled helpers

The skill ships scripts in its scripts folder: inventory.py, export_image_metadata.py, plan_transfer.py, validate_config.py and omero_common.py. All of them use argparse, so --help works without OMERO installed. Remote helpers are dry-run by default and only act when you pass --execute.

The skill bounds every list, page, ROI, annotation and file scan. It defaults to a secure connection, but secure transport does not by itself guarantee certificate hostname verification. Writes are treated separately, and cleanup of connections is required. The skill also tells the agent never to connect to a real server just to test examples.

Scripts run on your machine and the skill uses the network, so review what it will run and which server it will reach before you approve.

Remote helpers dry-run unless --execute is given
Every result set is limited; no group-wide exports without approval
Passwords and session keys are kept out of output, logs and tracebacks
OMERO data may include unpublished images and identifiers, so check authorisation first

Tips for good results

Name the group, object type and IDs in every request. The skill notes that an empty result in the current group does not prove an object is absent from other groups, so check group context if results look incomplete.

Keep requests small and review dry-run output before adding --execute or asking for any write. For background on permissions, filesets and web APIs, the skill's advanced reference covers the high-risk operations.

Start with a small limit and increase it only if needed
Ask for a dry run first on any import or write
Keep credentials in your secret manager, not in chat

What people use it for

A lab data manager lists the projects, datasets and images on an OMERO server, bounded to a set number of items.
A bioimaging researcher exports annotations or ROI shape geometry for named image IDs to JSON.
A developer writes a reviewed script that queries OMERO with the omero-py client, using the skill's connection pattern.
Someone plans an import or export locally with plan_transfer.py before any data moves.

Frequently asked questions

Is the OMERO agent skill free to use, and what is its licence?

The skill is released under the MIT licence, according to its listing. The upstream omero-py client is licensed separately under GPL-2.0-or-later, so check that licence if you distribute software that bundles it.

What do I need to install before using this skill?

You need Python 3.10 or newer, with 3.12 recommended, plus the omero-py client and a matching ZeroC IcePy wheel. You also need network access to an OMERO server you are authorised to use, and credentials set as OMERO_ environment variables.

Where do I put the skill so Claude can find it?

Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into .claude/skills/ in a project folder. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.

Can the skill upload or delete data on my OMERO server?

Writes such as uploads, annotations, imports and deletions are treated separately and need an exact, reviewed target. Remote helpers are dry-run by default and only act when --execute is given.

Why does my OMERO connection fail or return no results?

Check that OMERO_HOST, the port and your credentials are set, and that the server is reachable and you are authorised. Results can be empty in the current group even if an object exists in another group, so check group context.

How is this different from using omero-py directly?

The skill adds guardrails: bounded queries, dry-run defaults, credential handling rules and reviewed writes. Plain omero-py gives you the full API without these limits, so you must write and bound the code yourself.

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

Use this skill if you need a scoped, auditable inventory, metadata or ROI export from an OMERO server you are authorised to access, and you are comfortable setting environment-based credentials. Pick something else if you want general image analysis, pixel processing, or a simple connection with no setup, since this skill focuses on data access and requires careful credential handling.

Download the skill