How to use the scVelo RNA Velocity Analysis agent skill

What the scVelo skill makes the agent do

RNA velocity uses the ratio of newly made (unspliced) RNA to mature (spliced) RNA to estimate which direction cells are likely moving in gene-expression space. The skill tells the agent how to run this with scVelo on spliced and unspliced single-cell counts.

The agent can fit deterministic or dynamical models, examine gene phase portraits, build velocity graphs, estimate relative latent time, and rank velocity-associated genes. The skill also tells the agent to treat results as hypotheses. Velocity arrows are not observed cell movement, lineage tracing, causal drivers or proof of future cell fate.

• Fit deterministic or dynamical kinetic models
• Inspect individual genes with phase portraits
• Build velocity graphs and compute relative latent time
• Rank genes associated with velocity

How to install the scVelo agent skill

Download the ZIP file for the skill from the page where you found this guide. Unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only in that project.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the ZIP there.

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

Prepare the Python environment and input data

The tested stack targets Python 3.13. The skill's SKILL.md recommends uv for an isolated environment. Installing needs network access unless the packages are already cached. No API key is required.

Your input must be aligned spliced and unspliced counts, with cells as rows and genes as columns, stored in adata.layers['spliced'] and adata.layers['unspliced']. Counts must be finite and nonnegative. Do not use logged, scaled or batch-corrected values as counts. The skill cannot confirm from the numbers alone that data are raw, so check where they came from. Upstream quantification is outside this skill, so you need a velocity-aware quantifier to produce the two layers.

Read an H5AD file through AnnData, not scv.read, which the scVelo version in this skill does not provide. Loom files are supported through AnnData's loom reader, but AnnData deprecates loom, so convert to H5AD for further work.

• Keep the quantifier name and version, reference annotation, counting mode, sample IDs and barcode mapping
• Keep the original full-gene count file; retained-gene backups do not preserve filtered-out genes
• Check per-library coverage, doublets, ambient RNA and zero-count cells before fitting

Run the bundled workflow

The bundled script, scripts/rna_velocity_workflow.py, takes local files and does not download a demonstration dataset on startup. Run the commands from the skill directory. Input filenames and annotations in the examples are placeholders. Omit --groupby if you have no annotations, and use --no-plots to skip UMAP computation.

The script refuses to run preprocessing twice on the same data, rebuilds the raw-count geometry, applies log1p only to X, and writes results to output_dir/adata_velocity.h5ad. The Python function changes its argument in place, so pass adata.copy() if you need to keep the original object.

• Dynamical mode: use --mode dynamical with --groupby clusters
• Deterministic mode: use --mode deterministic
• Loom input: pass the loom file with --processed-h5ad to align raw counts to an existing annotation file

Read the evidence and its limits

After a dynamical run, inspect the evidence before you interpret it. The skill's reference notes that velocity is the derivative of spliced abundance under the fitted model, not a guaranteed biological program. Rates, scaling and inferred time can trade off, and snapshot data alone do not identify an absolute biological clock.

The workflow records warnings about nonfinite or constant time and coherence outputs in uns['velocity_workflow']['diagnostics']. A constant pseudotime does not support a trajectory ordering. Gene ranking is exploratory. Existing cluster labels stay as annotations and are not validated cell identities.

The dynamical estimator is not automatically more accurate than a steady-state estimator on every dataset, so compare the two where the data allow.

• Check the diagnostics record before reporting any ordering
• Treat ranked genes as candidates for follow-up, not causal drivers
• Use the model reference file, references/velocity_models.md, for assumptions and an optional CellRank handoff

Safety, network and known limits

The skill runs scripts. Its listing says it does not use the network during analysis. Local H5AD analysis needs no network or credentials. Network access is needed only to install packages, unless they are cached.

The default stochastic solver fails with NumPy 2. Current Scanpy requires NumPy 2, so installing an older NumPy beside it is not a fix. The skill's helper rejects this combination before it changes any data, and the legacy environment it describes was not run in the skill's review. The pandas 3 release is also incompatible with some dynamical fitting and plotting, so keep the pinned pandas version.

• Stochastic model: use the default deterministic or dynamical modes unless you have a separately validated legacy environment
• Keep the pinned pandas version in place
• Check the upstream 0.3.4 source when an online tutorial disagrees with the installed API