Skip to content
Get packs

Guide · Agent skill

How to use the FlowKit flow cytometry agent skill

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

FlowKit is a Python library for analyzing flow cytometry data, and this skill teaches an AI agent to use it for gating: applying spillover compensation, logicle transforms and hierarchical gates, then reporting event counts and percentages per population. This guide is for researchers, analysts and developers who want reproducible gate counts from FCS files or want to check a FlowJo 10 workspace analysis in Python. After reading it you will know how to install the skill, how to ask for gating work in plain language, and what the outputs mean.

FlowKit Flow Cytometry AnalysisK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings, then Capabilities, then Skills instead.
  2. 2Create the FlowKit environment. Run the uv commands from the install section to create a separate environment and install the pinned FlowKit release. Confirm that the import check prints a version.
  3. 3Gather your inputs. Collect your FCS files, your GatingML file or FlowJo workspace, and the group name if you use a workspace. Include single-stain controls if you need compensation.
  4. 4Ask for the analysis in plain language. Describe the gates or populations you want, the files, and any thresholds or controls you have. Mention whether you want a comparison with FlowJo.
  5. 5Run the helper and check the output. Let the agent run analyze_gates.py into a new output folder. Open gate_report.csv and confirm sample counts, parent counts and any rows flagged as undefined.
  6. 6Review the provenance file. Check provenance.json for input hashes and package versions so you can reproduce the run later.

What the FlowKit skill makes the agent do

An agent skill is a folder of instructions and helper files that an AI agent loads when a request matches the skill's description. This one covers flow cytometry analysis. Flow cytometry measures many individual cells, and researchers sort them into populations by drawing gates on plots. The skill tells the agent how to run that gating with the FlowKit library instead of doing it by eye.

The skill covers spillover compensation, logicle and biexponential transforms, hierarchical gating, GatingML strategies, and a subset of FlowJo 10 workspace features. It is meant for reproducible gate counts, population percentages, gated fluorescence summaries, and reproducing a FlowJo analysis in Python. For FCS metadata inspection or file-format repair alone, the skill directs you to FlowIO instead.

  • Applies compensation before nonlinear transforms and checks that gate thresholds use the same coordinate system
  • Builds or applies hierarchical gate strategies and keeps full gate paths including root
  • Reports event counts with denominators, gate paths, sample IDs and input hashes
  • Supports GatingML 2.0 and supported FlowJo 10 workspace features; the source states that import success alone does not establish agreement with FlowJo

Install the FlowKit skill (ZIP download or Claude upload)

Download the skill ZIP from this page. For Claude Code, unzip it into your user skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill limited to one project. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.

The skill needs its Python environment before it can run analyses. The skill's own instructions create a separate environment with uv, so FlowKit does not mix with your other Python packages. Installation needs network access. No API keys or accounts are required.

  • Requirements: Python 3.13 and the FlowKit release pinned in the skill's install notes; dependencies include FlowIO, FlowUtils, NumPy, pandas, SciPy, lxml and Bokeh
  • FlowUtils may need a C compiler only if a compatible prebuilt wheel is unavailable for your system
uv venv --python 3.13 .venv-flowkit uv pip install --python .venv-flowkit/bin/python "flowkit==1.3.2" .venv-flowkit/bin/python -c "import flowkit; print(flowkit.__version__)"

How to trigger the skill with natural requests

You do not need special syntax. Describe the analysis you want and mention your files. The skill's description matches requests about gate counts, population percentages, gated fluorescence summaries, FlowJo workspaces and reproducing a FlowJo analysis in Python. Mention the FCS files, the GatingML or FlowJo workspace file, and the group name if you have one.

Give the agent the actual gating strategy or control information when you have it. The skill asks for real thresholds and controls rather than inventing biological cutoffs, so a request that includes them will produce more useful results.

  • "Using gates.xml and sample.fcs, count events and percentages for each gate and write the results to a new folder."
  • "Reproduce the analysis in study.wsp for the group Study in Python and tell me where my counts differ from FlowJo."
  • "Apply compensation from my single-stain controls, then report the percent of CD4 positive events in each sample."
  • "Check whether these FCS files have duplicate sample IDs before running the batch."

Run the bundled analysis helper

The skill includes scripts/analyze_gates.py. For an existing GatingML strategy, the agent runs it on your FCS file. For a FlowJo workspace, you must supply every FCS file in the selected group. The helper writes gate_report.csv and provenance.json to a new output directory.

Each row of the report includes sample_event_count, parent_event_count and a full population_path. Where a parent has zero events, the percentage is left blank and flagged with relative_percent_defined set to False. The helper refuses duplicate sample IDs, missing or extra workspace-group samples, zero-event samples, and strategies with no gates. It uses only the files you list and does not follow paths embedded in the workspace.

  • Use --filename-as-id only when file basenames match the analysis definition, because the default ID is the FCS $FIL keyword
  • For large studies the helper loads each sample into memory, so run manageable batches or use the Python API
FLOWKIT_SKILL_DIR="skills/flowkit" uv run --no-project --python 3.13 --with "flowkit==1.3.2" python "$FLOWKIT_SKILL_DIR/scripts/analyze_gates.py" --workspace study.wsp --group "Study" --fcs sample-a.fcs sample-b.fcs --output-dir results-workspace

Read the results correctly

The count field is the number of events passing the gate and all its ancestors. absolute_percent is the percent of all events in the sample, and relative_percent is the percent of the immediate parent. Both are percentages, not fractions. Gate names can repeat under different parents, so identify a population by sample ID plus its full path.

Negative fluorescence after compensation is normal and should not be clipped to zero just so a logarithmic transform will run. The skill also asks you to state whether MFI means mean or median.

  • Zero events in a parent makes a child percentage undefined, which is different from a true 0% in an empty gate under a non-empty parent
  • Biological replicates should stay identifiable, because events from one specimen are not independent replicates

Build a gating strategy in Python

If you want to write your own strategy, ask the agent for a Python example. The skill's example loads a sample, adds a compensation matrix, a logicle transform and rectangle gates, then runs the analysis and prints a report. The matrix, thresholds and transform parameters in that example are synthetic teaching values, so replace them with your study's validated settings.

The example can also export a GatingML file. A template export does not preserve per-sample overrides, so use the per-sample export when a sample has its own gates.

  • Set compensation and transform references on each dimension that needs them
  • Export the report with sample IDs and gate paths so results can be checked later

What people use it for

  • Counting cells in each gate across a batch of FCS samples and exporting the counts with denominators
  • Checking whether a Python reproduction of a FlowJo 10 workspace agrees with the original FlowJo numbers for supported features
  • Building a repeatable gating pipeline where every input file is named explicitly
  • Summarizing gated fluorescence for a population after compensation and transformation

Frequently asked questions

Is the FlowKit skill free to use?

The skill is licensed under MIT. The FlowKit library itself is BSD-3-Clause licensed, as stated in the skill's instructions. The source does not list prices, and no API keys or accounts are needed.

What do I need to install before using it?

You need Python 3.13, network access for installation, and the uv tool to create the environment described in the skill. A C compiler is needed only if a compatible FlowUtils wheel is not available for your system.

Can it reproduce FlowJo results exactly?

The skill supports only a subset of FlowJo 10 features, and importing a workspace does not prove agreement with FlowJo. Compare representative samples against your FlowJo output before relying on the Python numbers.

Should I use this skill for clinical or diagnostic decisions?

No. The skill was tested only on synthetic data, and its thresholds are teaching values rather than biological validation. Use your study's validated controls and settings for any real analysis.

What if I only need to inspect FCS metadata or repair a file?

Use FlowIO instead. The FlowKit skill's description directs metadata inspection and file-format repair alone to FlowIO.

Why does my sample ID not match my filename?

By default FlowKit uses the FCS $FIL keyword as the sample ID, which can differ from the current filename. The helper's --filename-as-id option switches to file basenames, but use it only when those names match your analysis definition.

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 want scripted, repeatable gate counts and percentages from FCS files, or a Python check of a supported FlowJo 10 workspace, and you can verify the results against your own controls. Pick a different tool if you only need FCS metadata inspection or repair, which the skill itself sends to FlowIO, or if you need validated clinical or diagnostic output.

Download the skill