Agent skill

Stereopy Maintainer

by STOmics in STOmics/Stereopy

Stereopy project maintenance guide for code review, bug fixing, and feature development.

MITAuto-check passedDevelopment

Install Stereopy Maintainer

skills CLI
$ npx skills add STOmics/Stereopy --skill stereopy-maintainer -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install STOmics/Stereopy stereopy-maintainer --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/STOmics/Stereopy.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.cursor/skills/stereopy-maintainer .claude/skills/stereopy-maintainer && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
stereopy-maintainer
GitHub stars
293
Token cost
~1.7k tokens
SKILL.md length
583 words
Files
1
Skills in repo
2
Repo updated
First seen
Licence
MIT

At a glance

Stereopy project maintenance guide for code review, bug fixing, and feature development.

  • Works in 6 steps: KeyError in result.py — key not… → sparse/dense mismatch — code assumes… → H5AD format confusion — Stereopy adds… → …
  • Working on stereo/ source code
  • SKILL.md covers Architecture at a Glance, Critical Type Guards, Module Map and Known Bug Patterns, plus 5 more sections
  • Calls python, pip and pytest

What it does

Stereopy Maintainer is an agent skill from STOmics/Stereopy. Stereopy project maintenance guide for code review, bug fixing, and feature development. Use when working on stereo/ source code, fixing GitHub issues, reviewing PRs, adding tools or algorithms, modifying I/O formats, or debugging data pipeline errors.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Debugging and Data pipelines and ETL. It works with GitHub. The repository describes itself as: A toolkit of spatial transcriptomic analysis. The licence is MIT.

When your agent uses it

  • Working on stereo/ source code
  • Fixing GitHub issues
  • Modifying I/O formats
  • Debugging data pipeline errors

Example prompts

  • “/stereopy-maintainer”

Requirements

  • Python 3

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. KeyError in result.py — key not registered, or DataFrame column renamed
  2. sparse/dense mismatch — code assumes ndarray but gets csr_matrix
  3. H5AD format confusion — Stereopy adds custom groups (exp_matrix@raw, sn, layers)
  4. MSData scope_key — generate_scope_key(scope) not generate_scope_key(_names)
  5. mannwhitneyu overflow — NaN/inf or all-zero columns in input
  6. DataFrame column mismatch — df['gene_name'] vs df['genes'] vs var.index

What it can do on your machine

Read from SKILL.md and the folder at commit 2b21b00. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python
    • pip
    • pytest

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use pip, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Stereopy Maintainer loads about 1.7k tokens when it runs. Until then it costs about 68 tokens; SKILL.md has 583 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~68
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from STOmics/Stereopy at commit 2b21b00, republished under its MIT licence (© STOmics). 583 words, ~1,654 tokens.

Download SKILL.mdSave it as .claude/skills/stereopy-maintainer/SKILL.md (or your agent's skills folder).
name
stereopy-maintainer
description
Stereopy project maintenance guide for code review, bug fixing, and feature development. Use when working on stereo/ source code, fixing GitHub issues, reviewing PRs, adding tools or algorithms, modifying I/O formats, or debugging data pipeline errors.

Stereopy Maintainer Skill

Architecture at a Glance

StereoExpData (stereo/core/stereo_exp_data.py)
│  Core container: exp_matrix, cells, genes, position
│  exp_matrix: np.ndarray | scipy.sparse.spmatrix
│  bin_type: 'bins' | 'cell_bins'
│
├── .tl → StPipeline (stereo/core/st_pipeline.py)
│   │  Runs tools, stores results
│   └── .result → Result (stereo/core/result.py)
│       Dict-like, keys categorized by type:
│       CLUSTER: leiden, louvain, phenograph, annotation
│       REDUCE: umap, pca, tsne
│       CONNECTIVITY: neighbors
│       HVG: highly_variable_genes → renamed 'hvg'
│       MARKER_GENES: marker_genes → renamed 'rank_genes_groups'
│       SCT: sctransform
│
├── AnnBasedStereoExpData (AnnData-backed variant)
│   └── .tl.result → AnnBasedResult
│
└── MSData (stereo/core/ms_data.py)
    │  Multi-sample container, holds multiple StereoExpData
    └── .tl → MSDataPipeLine (stereo/core/ms_pipeline.py)

Critical Type Guards

Always check these before operating — runtime types vary:

VariablePossible TypesGuard
exp_matrixnp.ndarray, scipy.sparse.*issparse(m)
data.tl.result[key]dict, pd.DataFrameisinstance(v, dict)
Cell/Gene .to_df() columnsstr, object.astype(str)
H5AD formatstandard AnnData, Stereopy-extendedcheck for @ keys

Module Map

ModulePathResponsibility
Data modelstereo/core/stereo_exp_data.pyStereoExpData, AnnBasedStereoExpData
Cell/Genestereo/core/cell.py, gene.pyCell and Gene metadata containers
Pipelinestereo/core/st_pipeline.pyTool execution, @logit decorator
Multi-samplestereo/core/ms_data.py, ms_pipeline.pyMSData, scope management
Resultsstereo/core/result.pyResult, AnnBasedResult, key routing
Readerstereo/io/reader.pyMulti-format input (h5ad, gef, gem, loom, h5ms)
Writerstereo/io/writer.pyMulti-format output
H5AD helpersstereo/io/h5ad.pyLow-level HDF5 read/write
Toolsstereo/tools/*.pyHigh-level analysis (clustering, markers, dim_reduce)
Algorithmsstereo/algorithm/*.pyLow-level compute (mannwhitneyu, sctransform)
Plotsstereo/plots/*.pyVisualization
Configstereo/stereo_config.pyGlobal settings
Loggingstereo/log_manager.pylogger instance

Known Bug Patterns

When diagnosing issues, check these patterns first:

  1. KeyError in result.py — key not registered, or DataFrame column renamed

    • Check RENAME_DICT, CLUSTER_NAMES, MARKER_GENES_NAMES
    • Result value can be dict or DataFrame — caller must handle both
  2. sparse/dense mismatch — code assumes ndarray but gets csr_matrix

    • Always use issparse() before .toarray(), indexing, or arithmetic
    • exp_matrix type depends on file format and preprocessing history
  3. H5AD format confusion — Stereopy adds custom groups (exp_matrix@raw, sn, layers)

    • Standard AnnData readers won't find these
    • reader.py handles both formats, check isinstance(f[k], h5py.Group) vs Dataset
  4. MSData scope_key — generate_scope_key(scope) not generate_scope_key(_names)

    • scope is the correct parameter, not the internal _names attribute
  5. mannwhitneyu overflow — NaN/inf or all-zero columns in input

    • Pre-filter with x_mask for valid indices
  6. DataFrame column mismatch — df['gene_name'] vs df['genes'] vs var.index

    • Use .loc[df['genes'], 'real_gene_name'] pattern for safe access

Code Style

  • 4-space indentation, no tabs
  • Google-style docstrings with Parameters / Returns sections
  • Import order: stdlib → third-party (numpy, pandas, scipy, anndata) → local (stereo.*)
  • Logging: from stereo.log_manager import logger
  • Type hints optional but encouraged
  • Tools registered via StPipeline methods with @logit decorator

Development Workflow

Fixing a Bug
  1. Read the traceback — extract file path, line number, error type
  2. Locate the code — read the full function containing the bug
  3. Understand context — trace data flow through the pipeline
  4. Check type guards — is it a sparse/dense or dict/DataFrame issue?
  5. Minimal fix — only change what's broken
  6. Verify syntax — python -c "import ast; ast.parse(open('file.py').read())"
  7. Verify import — PYTHONPATH=. python -c "from stereo.module import Class"
  8. Commit — fix #N: brief description
Show full SKILL.md (206 more words)Show less
Adding a New Tool
  1. Create stereo/tools/your_tool.py
  2. Add method to StPipeline in stereo/core/st_pipeline.py
  3. Register result key in Result categories if needed
  4. Add corresponding test in tests/test_your_tool.py
  5. Add plotting if applicable in stereo/plots/
Adding a New Algorithm
  1. Create stereo/algorithm/your_algo.py or subpackage
  2. Wire it from a tool in stereo/tools/
  3. Handle sparse/dense input explicitly
  4. Add to __init__.py exports if public
Modifying I/O
  1. Reader changes go in stereo/io/reader.py
  2. Writer changes go in stereo/io/writer.py
  3. Low-level HDF5 operations use stereo/io/h5ad.py
  4. Always handle both h5py.Group and h5py.Dataset for H5AD keys
  5. Test with both standard AnnData and Stereopy-extended H5AD files

Testing

  • Test files: tests/test_*.py, pytest style
  • Stereopy has heavy dependencies — avoid pip install stereopy in CI
  • Use PYTHONPATH=. for import-based testing
  • For quick validation: AST parse + import check
  • Full test suite run via pytest tests/ -x --tb=short

File Format Reference

FormatExtReader FunctionNotes
H5AD.h5adread_stereo_h5adStereopy extended with @ groups
H5MS.h5msread_h5msMulti-sample, Stereopy-specific
GEF.gefread_gefBGI spatial format
GEM.gemread_gemTab-separated text
Loom.loomread_loomHDF5-based

Constraints

  • Only modify stereo/ and tests/
  • Never change pyproject.toml, .github/, or version numbers
  • requires-python: >=3.8, <3.9 — be careful with newer syntax
  • Dependencies managed in requirements.txt, not inline
  • MIT License

© STOmics, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .cursor/skills/stereopy-maintainer of STOmics/Stereopy.

Open the folder on GitHubat commit 2b21b00

Compare with similar skills

Stereopy Maintainer next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Stereopy Maintainer compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Stereopy Maintainer this skillSTOmics/Stereopy293—~1.7kAutomated safety check: PassMIT
Debugging Dagsastronomer/agents451—~1.9kAutomated safety check: PassApache-2.0
Exposed Bug Fix WorkflowJetBrains/Exposed9.3k—~3.8kAutomated safety check: PassApache-2.0
OpenCLI Adapter Autofixjackwener/OpenCLI30k1 repos~3.2kAutomated safety check: PassApache-2.0
Issue Fixmono/SkiaSharp5.6k—~5.1kAutomated safety check: PassMIT
React Router Bug Fix Workflowremix-run/react-router57k—~1.3kAutomated safety check: PassMIT

Similar skills

  • Debugging Dags

    astronomer/agents

    Comprehensive DAG failure diagnosis and root-cause analysis with structured investigation and prevention recommendations.

    451 GitHub stars~1.9k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Exposed Bug Fix Workflow

    JetBrains/Exposed

    Official

    Takes a GitHub or YouTrack issue for the Exposed project through reproduction, a failing test, a fix, validation and a pull request.

    9.3k GitHub stars~3.8k tokensUpdated today
    DevelopmentAuto-check passed
  • OpenCLI Adapter Autofix

    jackwener/OpenCLI

    Repairs a broken OpenCLI site adapter after a command fails: collects a trace, patches only the adapter, retries, and files an upstream GitHub issue once fixed.

    30k GitHub starsUsed in 1 repo~3.2k tokens
    DevelopmentAuto-check passed
  • Issue Fix

    mono/SkiaSharp

    Fix bugs in SkiaSharp C bindings. An agent skill from mono/SkiaSharp.

    5.6k GitHub stars~5.1k tokensUpdated today
    DevelopmentAuto-check passed
  • React Router Bug Fix Workflow

    remix-run/react-router

    Fixes a React Router bug reported in a GitHub issue end to end: fetching the issue, validating the reproduction, writing a failing test and implementing the fix on a new branch.

    57k GitHub stars~1.3k tokensUpdated today
    DevelopmentAuto-check passed
  • OpenROAD Bug Fixer

    The-OpenROAD-Project/OpenROAD

    Fixes an OpenROAD bug from a GitHub issue or error code: finds the root cause, implements the fix, adds a regression test and prepares a signed-off commit.

    3.2k GitHub stars~784 tokensUpdated today
    DevelopmentAuto-check passed

More from STOmics/Stereopy

  • Stereopy Issue Responder

    STOmics/Stereopy

    Generates professional maintainer-grade responses for Stereopy GitHub issues.

    293 GitHub stars~1.3k tokensUpdated 2 mo ago
    Auto-check passed

Works with

Questions about Stereopy Maintainer

What does Stereopy Maintainer do?

Stereopy project maintenance guide for code review, bug fixing, and feature development. Stereopy Maintainer is an agent skill from STOmics/Stereopy. Stereopy project maintenance guide for code review, bug fixing, and feature development.

When should I use Stereopy Maintainer?

Stereopy Maintainer fits situations like: working on stereo/ source code; fixing GitHub issues; modifying I/O formats; debugging data pipeline errors.

How do I install Stereopy Maintainer in Claude Code?

Run `npx skills add STOmics/Stereopy --skill stereopy-maintainer -a claude-code`. Or copy the skill folder (.cursor/skills/stereopy-maintainer in STOmics/Stereopy) into .claude/skills/stereopy-maintainer in your project. Claude Code loads it when a task matches its description.

How do I install Stereopy Maintainer in Codex?

Run `npx skills add STOmics/Stereopy --skill stereopy-maintainer -a codex`. Or copy the skill folder (.cursor/skills/stereopy-maintainer in STOmics/Stereopy) into .agents/skills/stereopy-maintainer in your project. Codex loads it when a task matches its description.

Can I use Stereopy Maintainer in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add STOmics/Stereopy --skill stereopy-maintainer -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/stereopy-maintainer, .gemini/skills/stereopy-maintainer, .github/skills/stereopy-maintainer and .opencode/skills/stereopy-maintainer in your project.

What does Stereopy Maintainer need to run?

Going by SKILL.md and its folder, Stereopy Maintainer needs the command-line tools its instructions call (python, pip and pytest). Our summary lists: Python 3.

Does Stereopy Maintainer access the network?

SKILL.md contains no URLs. Its commands use pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Stereopy Maintainer safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Stereopy Maintainer use?

Stereopy Maintainer is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Stereopy Maintainer use?

About 1.7k tokens (SKILL.md is roughly 6.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Stereopy Maintainer?

Skills that share tags, products or a category with Stereopy Maintainer: Debugging Dags (astronomer/agents, 451 stars), Exposed Bug Fix Workflow (JetBrains/Exposed, 9.3k stars), OpenCLI Adapter Autofix (jackwener/OpenCLI, 30k stars) and Issue Fix (mono/SkiaSharp, 5.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Stereopy Maintainer?

STOmics (a GitHub organization) maintains it in STOmics/Stereopy, which has 293 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on July 17, 2026.

Source: STOmics/Stereopy on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.