Skip to content
Get packs

Guide · Agent skill

How to use the DeepSpot-M spatial transcriptomics agent skill

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

DeepSpot-M is a research model that estimates gene activity from ordinary H&E stained tissue images, a approach called virtual spatial transcriptomics. This guide covers the deepspot-m agent skill: what it lets your agent do, how to install it, how to get access to the gated model weights, and how to phrase requests so the agent uses it correctly. By the end you will know the input rules, the limits of the predictions and the licence conditions that apply.

DeepSpot-M Spatial TranscriptomicsK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download and unzip the skill. Download the deepspot-m ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ or a project's .claude/skills/, or upload the ZIP under Settings, Capabilities, Skills in the Claude apps.
  2. 2Install the Python package. Make sure Python 3.10 or newer and PyTorch are available, then run uv pip install deepspotm==1.0.0 in an isolated environment.
  3. 3Request model access. Open the DeepSpot-M page on Hugging Face and request access to the gated weights. Wait for approval before continuing.
  4. 4Authenticate the machine. Once approved, run hf auth login or set HF_TOKEN so the weights can be downloaded. Keep tokens out of your code.
  5. 5Ask for a concrete task. Request one step at a time, such as checking tile size or predicting a short list of gene symbols from 224x224 tiles at about 20x.
  6. 6Review and label results. Keep gene columns labelled and treat all outputs as predictions that need validation against paired assays.

What the deepspot-m skill makes the agent do

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches the skill's description. The deepspot-m skill teaches the agent how to work with DeepSpot-M, which maps a 224x224 H&E histology tile to predicted spatial gene expression in log1p-CPM, one value per queried gene per tile.

The skill covers loading the model, querying genes by HGNC symbol from the released panel of about 19k protein-coding genes, checking that tiles meet the size and magnification rules, and guiding whole-slide prediction after tiling with histolab. It also explains the licensing and access rules.

  • Predict gene expression for chosen genes from 224x224 RGB tiles at about 20x (about 0.5 microns per pixel)
  • Query genes by symbol and get values back aligned with your gene list
  • Choose among five frozen gene embedding sources: evo2, orthrus, prott5, scgpt and apertus
  • Plan whole-slide runs: tile on a tissue grid, batch inference, then join coordinates by tile ID

Install the skill from the ZIP

Download the deepspot-m ZIP from this page and unzip it. You have two options depending on how you use your agent.

For Claude Code, place the unzipped skill folder in ~/.claude/skills/ to make it available everywhere, or in .claude/skills/ inside a specific project to make it available only there.

In the Claude apps, upload the ZIP under Settings, then Capabilities, then Skills.

  • Personal install: ~/.claude/skills/ (available across your projects)
  • Project install: .claude/skills/ inside the project folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Set up the Python package and Hugging Face access

The skill needs Python 3.10 or newer and PyTorch. CUDA is optional because CPU is supported. Install the package in an isolated environment with the command below, and install the PyTorch build that matches your CUDA runtime if you have a GPU.

The model weights are gated. First request access on the DeepSpot-M Hugging Face page at https://huggingface.co/ratschlab/DeepSpotM and wait for approval. Approval and authentication are separate steps: once approved, log in on the machine that will download the weights. You can also provide an HF_TOKEN environment variable instead. Do not paste tokens into code.

  • Required: Python 3.10 or newer, PyTorch, the deepspotm package from PyPI, an approved Hugging Face account
  • Optional: histolab in a separate Python 3.10 or 3.11 environment with OpenSlide, for whole-slide tiling
  • Optional: AnnData, for exporting H5AD files
uv pip install deepspotm==1.0.0 hf auth login

Trigger the skill with natural requests

You do not need special syntax. Name the task and the data in plain language, and mention DeepSpot-M or spatial transcriptomics from H&E so the agent matches the skill. Good requests state the tile size, the genes and what you want back.

Vague requests such as analyse my slide may not match the task well. Ask for one concrete step at a time, such as checking a tile or predicting a short gene list.

  • Predict EPCAM and CD3D log1p-CPM values for this 224x224 H&E tile using DeepSpot-M
  • Check whether these PNG tiles are 224x224 at about 20x before running the model
  • Which of these gene symbols are in the DeepSpot-M released panel?
  • Plan a whole-slide DeepSpot-M run with histolab tiling and batched inference

Check inputs before you trust outputs

The model expects 224x224 RGB tiles at roughly 20x. Pixel dimensions alone do not prove magnification, so the skill asks the agent to read the physical resolution metadata and not infer 20x from a level number. If a crop is the wrong size, the agent should re-tile or resample it, and record the transform.

Gene symbols must appear in the released panel (model.gene_names). An unknown symbol raises a KeyError that names the offending genes. Keep the gene list beside the output so the columns stay labelled.

  • Tile size must be 224x224 RGB
  • Read both MPP axes and the level downsample factors before choosing a level
  • Symbols must be HGNC symbols in the released panel; genes outside it cannot be queried in this release

Run whole-slide prediction safely

Whole-slide prediction is a tiling step followed by batched inference. Tile first, keep each tile's level-0 bounding box and measured output resolution, run predict_genes once per batch with the same gene list, then concatenate results in a recorded tile-ID order. Join coordinates by tile ID and check for duplicates and missing tiles rather than relying on row order.

The skill recommends running tiling in a separate environment and passing PNG tiles plus a coordinate manifest to the inference environment. Label every output as a model prediction, not a measured transcript count.

  • Verify slide resolution before tiling
  • Check tile IDs for uniqueness and missing tiles
  • Validate on held-out slides with paired assays for the tissue you care about

What people use it for

  • Researchers exploring how predicted expression of marker genes varies across regions of an H&E tumour section
  • Bioinformaticians building a pipeline that maps predicted gene values back onto tissue tile coordinates
  • Developers adding an optional DeepSpot-M step to a larger project that must still run without the model installed
  • Teams planning a whole-slide tiling run that exports results to H5AD for downstream analysis

Frequently asked questions

How do I install the DeepSpot-M agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings, then Capabilities, then Skills.

What do I need to run DeepSpot-M?

You need Python 3.10 or newer, PyTorch (CUDA optional), the deepspotm package from PyPI, and an approved Hugging Face account with access to the gated weights. Authenticate with hf auth login or HF_TOKEN. Whole-slide tiling with histolab additionally needs OpenSlide in a separate Python 3.10 or 3.11 environment.

Is DeepSpot-M free to use commercially?

No. The code is under PolyForm Noncommercial and the weights are CC-BY-NC-SA-4.0. The access form limits eligibility to academic or public nonprofit researchers without concurrent commercial affiliations, so read the live declarations before requesting access.

Can I use DeepSpot-M for clinical or diagnostic decisions?

No. The model is for research use only and not for clinical or diagnostic use. Its outputs are predictions, not measured gene expression.

Why does my gene symbol raise a KeyError?

The symbol is not in the released panel of about 19k protein-coding genes. The error names the offending genes. Check symbols against model.gene_names, and note that genes outside the panel cannot be queried in this release.

Does the skill work without a GPU?

Yes. CPU is supported and CUDA is optional. Expect slower inference on CPU, especially for whole-slide runs.

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 are an academic or nonprofit researcher, or a bioinformatician working on research pipelines, who wants an agent to help run DeepSpot-M on H&E tiles with correct input checks. Pick another tool if you need clinical or diagnostic output, commercial use, or measured gene expression from an assay.

Download the skill