Guide · Agent skill
How to use the FlowIO FCS File Reader agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
FlowIO is a Python library for reading and writing Flow Cytometry Standard (FCS) files, the format most flow cytometers save measurements in. This skill gives an AI agent the instructions and a helper script to open those files, list their metadata and channel names, pull out measurements as a table-like array, and create new FCS files. After reading this guide you will know what the skill does, how to install it, how to ask for it in plain language, and where it stops.
FlowIO FCS File ReaderK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the skill ZIP from this page and unzip it. You should end up with a flowio folder that contains SKILL.md.
- 2Place the folder or upload it. Copy the folder into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings, then Capabilities, then Skills.
- 3Install FlowIO. Run uv pip install "flowio==1.4.0" in your Python environment, then check the import with uv run python -c "import flowio; print(flowio.__version__)".
- 4Ask with a file and a goal. Name your FCS file and say what you want, such as listing channels or exporting a table. Mention if you need scaled or raw values.
- 5Check the result. Ask the agent to reopen any file it creates and confirm event count, channel count and labels match what you expected.
What the FlowIO skill makes the agent do
An agent skill is a folder of instructions and optional scripts that an AI agent loads when a task matches its description. This one covers low-level FCS work: reading FCS 2.0, 3.0 and 3.1 files, inspecting the header, text (metadata) and channel information, returning event data as a two-dimensional NumPy array, reading older files that contain several datasets, exporting tables, and writing list-mode FCS 3.1 files.
The skill is deliberately narrow. FlowIO does not perform compensation, logicle or biexponential transforms, gating, clustering, or FlowJo workspace processing. The skill directs those tasks to FlowKit or another analysis package.
- Read and summarise metadata and channel names
- Extract event values for pandas or machine-learning pipelines
- Handle files that hold more than one dataset
- Create a new FCS 3.1 file from a NumPy array
Install the FlowIO skill with a ZIP download
Download the skill ZIP from this page and unzip it. Put the resulting folder in one of two places depending on how you use your agent.
For a personal setup in Claude Code, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder so it applies only there.
In the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.
- Personal, all projects: ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload
What you need before you start
The skill needs a Python version that FlowIO supports, the uv tool, and the FlowIO library itself. FlowIO installs NumPy automatically. pandas is optional and only needed for DataFrame workflows.
Install the pinned release with uv, then confirm that Python can import it. The skill's examples target the pinned release, so use that command rather than an unpinned install.
- A supported Python version (check the list in the skill's compatibility notes)
- uv
- FlowIO, installed with NumPy
- pandas, optional
uv pip install "flowio==1.4.0"Ask for it with natural requests
You do not need to name the skill. The agent reads each skill's description and loads FlowIO when your request involves FCS files and the kinds of work it covers. Name the file and say what you want to know or produce.
Requests that suit FlowIO describe a metadata question, a channel question, a data export, or a new file. If your request is about compensation, gating or FlowJo, the agent should point you to FlowKit instead.
- Which channels are in sample.fcs, and what instrument and date are listed?
- Export the event data from run_03.fcs to a CSV file with the channel names as headers.
- Does this FCS file contain more than one dataset? If so, how many events does each have?
- Make a 3-channel FCS 3.1 file from this NumPy array, then reopen it and check the counts.
- Compensate and gate these FCS files. (Ask FlowKit instead; FlowIO does not do this.)
Examples of what the agent runs
For a metadata-only check, the agent loads the file without reading the event data, which is faster for large or unfamiliar files. The skill also tells the agent to choose event scaling explicitly and to reopen any file it writes to confirm the counts and labels.
A typical metadata check looks like this:
- Metadata-only loads avoid reading the event data.
- Channel numbering in the NumPy array starts at zero, while FlowIO's channel list starts at one. The agent is told to keep these straight.
- TEXT keys are lowercase, so the agent looks up date and cyt rather than uppercase keywords.
from flowio import FlowData
flow = FlowData("sample.fcs", only_text=True)
print(flow.version, flow.event_count, flow.pnn_labels)Safety notes: scripts, network and sensitive metadata
The skill includes a script, scripts/inspect_fcs.py, and its allowed tools include Bash, so the agent can run commands on your machine. Read the script before you rely on it in a sensitive environment. The skill states that parsing runs locally and needs no credentials or network access.
FCS metadata can contain sample, subject, operator and instrument identifiers. Do not share files containing such identifiers outside a controlled environment. The skill tells the agent to export only the fields a task needs.
- Runs scripts: yes
- Uses network: no
- Keep identifying metadata inside controlled systems
- Check written files by reopening them
Tips and limits for better results
Tell the agent whether you want scaled values or raw decoded values. The skill's default preprocessing applies gain, log and time scaling from the file's metadata. It does not apply compensation or display transforms, so state that in your request if those matter.
FlowIO does not provide chunked or memory-mapped access, so very large files load fully into memory. For multi-dataset files, give the agent a file path rather than an open file handle.
- Specify preprocessing: scaled or raw values
- Expect FCS metadata values to be strings
- Use FlowKit for compensation, transforms, gating and FlowJo workspaces
- Ask the agent to validate exports by reopening them
What people use it for
- Confirming which fluorescent channels a run contains before starting analysis
- Exporting event values to pandas for a machine-learning pipeline
- Checking the acquisition date and instrument recorded in a batch of FCS files
- Splitting out datasets from an older multi-dataset FCS file
- Writing a small FCS 3.1 test file from a NumPy array to test downstream software
Frequently asked questions
Is the FlowIO agent skill free?
The skill is listed under the MIT licence on this directory. The SKILL.md file itself names a BSD-3-Clause licence, so check the licence file in the skill's repository before redistributing it. FlowIO is a separate open-source Python library that you install with uv.
Does the FlowIO skill need an internet connection?
No. The skill states that parsing runs locally and needs no credentials or network access. Installing FlowIO itself does require a package download.
What is the difference between FlowIO and FlowKit?
FlowIO reads, inspects and writes FCS files at a low level. FlowKit is the tool the skill points to for compensation, cytometry transforms, gating and FlowJo workspaces. Use FlowIO to get the data out of a file and FlowKit to analyse it.
Can FlowIO read FCS 2.0 files?
Yes. The skill says FlowIO reads FCS 2.0, 3.0 and 3.1 files. It can also read legacy files that contain multiple datasets, though the FCS 3.1 specification deprecated that feature.
Why does my FlowIO import fail after installing?
Check that the agent or your shell is using the Python environment where you installed FlowIO, and that your Python version is one the library supports. The skill includes a troubleshooting reference file that covers common errors.
Does FlowIO do compensation or gating?
No. The skill says FlowIO does not perform compensation, logicle or biexponential transforms, gating, clustering or FlowJo workspace processing. Ask the agent to use FlowKit for those steps.
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 an agent to inspect FCS metadata, pull measurements into a table, or write simple FCS 3.1 files, and you are comfortable with a skill that can run a local script. Pick FlowKit or another analysis package if your work centres on compensation, gating or FlowJo workspaces.
Download the skill