How to use the Scanpy single-cell analysis agent skill

What the Scanpy skill makes the agent do

Once installed, the agent can run a single-cell RNA sequencing analysis with the Scanpy toolkit. Typical work includes quality control, normalizing counts, highly variable gene selection, PCA, UMAP and t-SNE, Leiden clustering, ranking marker genes for each cluster, preparing pseudobulk data, and making plots.

The skill also converts Seurat or SingleCellExperiment R objects (.rds, .RData) to .h5ad files so Scanpy can load them. The agent is told to prefer the bundled scripts over writing code from scratch, and it warns about common statistical pitfalls such as confounded designs and cell-type labels that have not been reviewed.

Install the skill from the ZIP file

Download the ZIP for the scanpy skill from this page, then unzip it. The folder must contain SKILL.md at its top level, along with the scripts, assets and references folders.

For a personal setup, place the unzipped folder in ~/.claude/skills/. To limit the skill to one project, place it in that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal use: unzip into ~/.claude/skills/
• Single project: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Install Scanpy and the Python requirements

The skill requires Python 3.12 or newer and Scanpy with the leiden extra, which installs the igraph and leidenalg packages used for clustering. The skill also depends on anndata. Install Scanpy with uv:

Some branches need optional packages: harmonypy, bbknn, scikit-misc, scikit-image, loompy or dask. Install only the ones your analysis needs. R is needed only for converting .rds, .RData, Seurat or SingleCellExperiment inputs.

Trigger the skill with natural requests

You do not need special syntax. Describe the task and mention your data file. The agent should pick the skill when your request matches its scope, such as quality control, clustering, marker genes or UMAP plots for scRNA-seq data.

Good requests name the input, the goal and any known structure in the data, for example the sample or batch column. If you want a specific step, say so.

• Check whether my pbmc.h5ad file has raw counts and summarize what is already computed.
• Run QC on raw.h5ad, filter low-quality cells, and show before and after plots.
• Cluster my processed data at resolutions 0.3, 0.6 and 1.0 and rank marker genes for each cluster.
• Convert my Seurat object sample.rds to h5ad, then run the full pipeline.

Run the scripts step by step

The skill bundles CLI scripts in its scripts folder. Each script reads and writes .h5ad files, so the outputs chain together, and each has its own --help option. Figures are saved to ./figures/ by default. The scripts include run_pipeline.py for a full workflow in one command, inspect_data.py for summarizing an unknown dataset, convert.py for loading 10x, csv, loom or mtx input, qc_analysis.py, preprocess.py, reduce_dimensions.py, batch_correct.py, cluster.py and find_markers.py.

Use the full pipeline for a first pass, or run the steps separately when you want to check each result. Run the scripts from the skill directory or pass full paths.

• Full workflow: run_pipeline.py takes load, QC, normalization, HVG, PCA, optional batch correction, UMAP, Leiden and markers in one command
• Inspect first: inspect_data.py reports shape, layers and whether data are raw or normalized
• Convert: convert.py writes .h5ad from 10x directories, csv, loom or mtx

Safety, data requirements and limits

The scripts reject negative, fractional, nonfinite or zero-total cells. Input to QC must be identified raw counts. If your X matrix is already normalized, tell the agent and use the counts layer option. The skill does not infer provenance from integer-looking values, so check this yourself when the metadata is unclear.

The skill runs scripts and does not use the network. Local analysis needs no credentials. The toolkit loads data into memory, so it is not a general out-of-core pipeline for very large datasets. Cell-type mappings and marker signatures in the assets are illustrative human examples that need expert review. Results are exploratory and not biologically validated, and they are not for clinical or diagnostic decisions.

• Clinical or diagnostic use is out of scope
• Datasets without a declared counts layer may produce wrong results
• Batch correction changes coordinates or the graph, so keep original counts for differential expression

Tips for more reliable results

Run inspect_data.py before anything else so you know which layers and raw data are present. Keep a full-gene object for pseudobulk work, since the full pipeline keeps one. When you compare conditions, use independent biological replicates; aggregating cells cannot fix missing replication or confounded design.

Treat cluster numbers as labels, not cell types. Check marker genes against known biology before naming a cluster. Markers found on the same data used to define clusters are exploratory.

• Use independent biological replicates for condition comparisons
• Name cell types only after expert review of markers
• Save intermediate .h5ad files so each step can be checked