---

name: stanobj description: > Use when the user asks to "standardize single-cell data", "convert to h5ad", "convert Seurat to h5ad", "convert RDS to h5ad", "standardize scRNA-seq", "convert 10x to h5ad", "convert CSV/TSV expression matrix", "convert MTX files", "read Seurat object", "convert SingleCellExperiment", "harmonize single-cell metadata", or mentions converting any single-cell format (rds, mtx, csv, tsv, h5, hdf5, loom) into canonical h5ad. Do NOT use for reading/inspecting existing h5ad files (that is scrna-reader), gene ID conversion (that is stangene), or biological analysis (PCA, clustering, etc). version: 1.0.0 allowed-tools: [Bash, Read, Glob, Grep]

stanobj — Standardize Single-Cell Data to Canonical h5ad

Convert heterogeneous single-cell transcriptomics datasets into canonical, analysis-ready .h5ad files with full provenance tracking.

Supported Formats

| Format | Extension | Reader | |--------|-----------|--------| | Matrix Market / 10x triplet | .mtx, directory | mtx_reader | | CSV expression matrix | .csv, .csv.gz | csv_reader | | TSV expression matrix | .tsv, .tsv.gz | csv_reader | | 10x Genomics HDF5 | .h5 | h5_reader | | Generic HDF5 | .h5, .hdf5 | h5_reader | | Existing h5ad | .h5ad | h5ad_reader | | Loom | .loom | loom_reader | | Seurat RDS | .rds | seurat_reader (R subprocess) | | SingleCellExperiment RDS | .rds | sce_reader (R subprocess) |

Archives supported: .tar.gz, .tgz, .tar.bz2, .tar, .zip Compression: .gz, .bz2 (transparent for most formats)

Workflow

1. Identify the input file/directory from the user's request
2. Ask the user for an output path (required: -o <path.h5ad>)
3. Run the orchestrator:

python ~/.claude/skills/stanobj/scripts/stanobj.py <input> -o <output.h5ad>

4. Check the exit code:

   • Exit 0: Success. Read the audit log and present a summary to the user.
   • Exit 10: Decision needed. Parse the JSON from stdout, present options to the user (or decide if obvious), then re-invoke with --decision <type>=<choice>.
   • Exit 1: Fatal error. Read stderr and report to user.

5. After success, optionally suggest running scrna-reader to verify the output.

Decision Protocol

When the orchestrator cannot proceed autonomously, it exits with code 10 and prints a JSON decision request to stdout:

{
  "status": "decision_needed",
  "decision_type": "assay_selection",
  "context": "Seurat object has 3 assays: RNA, SCT, ADT",
  "options": ["RNA", "SCT", "ADT"],
  "recommendation": "RNA",
  "reason": "RNA has the most features and contains raw counts"
}

Re-invoke with: --decision assay_selection=RNA

Multiple decisions can be supplied: --decision assay_selection=RNA --decision matrix_type=counts

Known Decision Points

| Type | Trigger | Options | |------|---------|---------| | format_detection | Unrecognized file format | format names | | assay_selection | Multiple assays in Seurat/SCE | assay names | | matrix_orientation | Ambiguous CSV/TSV layout | cells_x_genes, genes_x_cells | | matrix_type | Low-confidence classification | counts, normalized, log1p, scaled, unknown | | layer_selection | Multiple candidate layers | layer names | | modality_filter | Mixed RNA + non-RNA features | rna_only, keep_all |

Outputs

Three files per conversion:

<output>.h5ad               # Canonical AnnData
<output_stem>_report.json   # Machine-readable report
<output_stem>_audit.log     # Human-readable audit log

Canonical Schema

See references/canonical-schema.md for the full target schema.

Key conventions:

• adata.X = main analysis matrix
• adata.layers["counts"] = raw counts when available
• adata.obs["cell_id"] = original cell barcode
• adata.obs["dataset"] = dataset name
• adata.var["gene_symbol"] = gene symbols
• adata.var["gene_id"] = Ensembl IDs if available
• adata.uns["stanobj"] = conversion provenance

Scope Boundaries

• This skill does NOT convert gene IDs — that is stangene
• This skill does NOT inspect/compare/merge existing h5ad — that is scrna-reader
• This skill does NOT perform biological analysis