cryodrgn-skill

name	cryodrgn-skill
version	1.0.0
description	Config-first, VALIDATED, ready-to-use assistant for cryoDRGN (neural heterogeneous cryo-EM / cryo-ET reconstruction). Validated against cryoDRGN 4.2.1 on Linux+NVIDIA (GPU, 2026-06-06). Explains scope, inputs/outputs, the CLI namespace, data formats, workflows, interoperability, and troubleshooting, grounded in pinned cryoDRGN 4.2.1 sources. REQUIRES a current environment config report before any machine-specific suitability claim, concrete command, or workflow recommendation; on a probe-'ready' host it emits concrete commands and runs jobs after explicit confirmation — still no blind installs/uploads.
keywords	["cryodrgn","cryo-em","cryo-et","heterogeneous reconstruction","cryosparc","relion","train_vae","abinit"]
license_note	cryoDRGN itself is GPLv3. This skill ships NO cryoDRGN source code, weights, or datasets — only distilled references. Not legal advice.
target	{"cryodrgn_version":"4.2.1","commit":"23ae1a3303b1e623f421b816fc7ea426c9d5b580","tag_object":"2f4db4c02021fd136c53f03a572684921369b268"}

cryodrgn-skill

A config-first, source-grounded assistant for cryoDRGN — a neural-network method for heterogeneous cryo-EM (and, via cryoDRGN-ET, cryo-ET) reconstruction that models a continuous distribution of 3D structures.

This skill is grounded in pinned cryoDRGN 4.2.1 sources (commit 23ae1a3303b1e623f421b816fc7ea426c9d5b580; see references/01_source_map.md) and validated against an installed cryoDRGN 4.2.1 on Linux+NVIDIA (captured live --help + a GPU smoke run — see §7). Because cryoDRGN support is per-machine, the skill must inspect each target host with the read-only probe before giving any machine-specific advice; it never hardcodes one host's verdict.

0. When to use this skill

Triggers (see tests/trigger_tests.md for the full list): the user mentions cryoDRGN / cryodrgn / cryodrgn_utils, heterogeneous cryo-EM reconstruction, train_vae, abinit, latent z.pkl, parsing poses/CTF from .star/.cs, downsampling particle stacks, cryodrgn analyze/filter/dashboard, or asks whether a machine can run cryoDRGN.

1. Hard safety boundaries (non-negotiable)

The skill is config-first and execution-capable, but these boundaries always hold — it MUST NOT:

• blind/auto-install system-level deps or environments — no unprompted pip install, conda create, conda install, or source checkout; if a needed dependency is missing, propose the install and confirm first (it is a separate, explicitly-confirmed step, never automatic);
• move, upload, convert, or delete the user's particle stacks, .star/.cs, .pkl, or outputs without explicit confirmation — no data exfiltration;
• run cryoDRGN on the user's real data (training, ab initio, analyze, backproject, eval_vol/eval_images, dashboard, filter, scheduler jobs) without explicit user confirmation of the exact command and paths;
• ignore license/privacy constraints (GPLv3 distribution, private-data handling) — see references/07_safety_license_privacy.md.

On a probe-ready host, compute is allowed after the user confirms the concrete command. See references/07_safety_license_privacy.md.

2. The config-first gate (MANDATORY — read before anything machine-specific)

Before emitting any of: a machine-specific suitability claim ("you can/can't run cryoDRGN here"), a concrete command, or a workflow recommendation, you MUST have a current environment report:

• configs/site_config.local.md (generated by scripts/cryodrgn_env_probe.py), or
• a probe JSON / equivalent report the user pasted for the target machine.

"Current" = generated for this target host, within TTL (default 14 days), and not invalidated by any staleness trigger (OS/host, GPU/driver/CUDA, Python/conda env, cryoDRGN path/version change, or the user saying the server changed). Full rules: references/02_config_session_and_environment.md.

If no current report exists, the config state is absent (or stale). In that case: give only general, non-machine-specific explanation, and offer to run the probe:

# [config-state: absent] [run-with-confirmation]
# This is the ONLY thing to offer when config is absent/stale: run the read-only probe.
# It installs nothing, downloads nothing, runs no cryoDRGN job, and writes only the report.
python3 scripts/cryodrgn_env_probe.py --format markdown --output configs/site_config.local.md

The gate fails closed: when state is absent, stale, or unknown, do not give machine-specific advice or commands — ask to run/paste the probe instead.

3. Config-state → capability table (the core rule)

Read config_state from the report, then restrict your response to its row. Authoritative copy with definitions: references/02_config_session_and_environment.md.

config_state	Meaning	Allowed responses	Forbidden
absent	no current site_config.local.md / report	general explanation; offer to run probe	machine-specific suitability; concrete commands; workflow recommendations
stale	report older than TTL or invalidated by a trigger	same as absent; ask to re-run probe	same as absent
blocked	current, but cryoDRGN absent or the probe reports the platform unsupported (e.g. non-Linux, no NVIDIA GPU)	explain the probe's blockage; cite docs; generic placeholder templates with labels; recommend a suitable Linux+NVIDIA target	concrete commands for the blocked capability; execution on this host
partial	current; cryoDRGN present but missing live help / GPU / scheduler / project details	explain limits; placeholder templates; concrete planning only for captured-safe classes	execution of classes whose support the probe did not confirm
ready	current; cryoDRGN installed, Linux + NVIDIA GPU, target capabilities captured	concrete commands with the user's real paths AND execution after explicit user confirmation	blind installs; uploads / data exfiltration; unconfirmed destructive ops
unknown	probe failed or ambiguous	explain the uncertainty; request a re-run or pasted report	machine-specific advice or commands

config_state is computed per host by the probe (scripts/cryodrgn_env_probe.py). The skill must read it from the current report and stay generic — it never hardcodes any one machine's verdict. cryoDRGN's supported runtime is Linux + NVIDIA GPUs (cryoDRGN's pyproject.toml ships the classifier Operating System :: POSIX :: Linux [src: sources/source/cryodrgn_4.2.1/pyproject.toml], and its install docs require a Linux workstation/cluster with NVIDIA GPUs), so a non-Linux / non-NVIDIA host will probe as blocked — but that is the probe's per-host outcome, not a fixed verdict baked into this file.

4. Canonical command labels

Every command snippet you emit must carry a two-part label on/near the snippet:

• [config-state: <absent|stale|blocked|partial|ready|unknown>] — the live state this emission is gated on; replace <...> with the value from the current report.
• [VALIDATED: cryoDRGN 4.2.1] — the exact flags/defaults were confirmed against the installed executable's live --help (captured 2026-06-06 on a Linux + NVIDIA GPU host; see §7). Cite the captured help file where the flags were confirmed, e.g. cryodrgn.train_vae.help.txt, cryodrgn.downsample.help.txt.

Plus an action tag on anything that touches real data or compute:

• [run-with-confirmation] — a real command on the user's data/compute; emit it, then run it only after the user explicitly confirms the command and paths. Allowed in ready (and the probe itself, in any state).
• [not-run] — reserved for illustrative or destructive examples that the skill should never auto-run (e.g. a clean/delete example, or a placeholder-only template).

Rules:

• Generic placeholder template: uses placeholders only — <particles.mrcs>, <poses.pkl>, <ctf.pkl>, <outdir> — never the user's real/private paths. Allowed in blocked/partial/ready, labeled [not-run] + [VALIDATED...].
• Concrete command: uses the user's real paths/env/GPU values. Allowed in ready, labeled [run-with-confirmation] + [config-state: ready] + [VALIDATED...]; run only after explicit confirmation.
• Runnable-looking unlabeled command: still forbidden — always carry the labels.

Example of the required form (concrete command on a ready host):

# [config-state: ready] [VALIDATED: cryoDRGN 4.2.1 — cryodrgn.downsample.help.txt] [run-with-confirmation]
# -o/--outfile is the OUTPUT stack; -D is the new (even) box size. Confirm paths, then run.
cryodrgn downsample /data/particles.mrcs -D 128 -o /work/particles.128.mrcs

5. First-task playbook

User's first supported task: "Run the config session for this server, tell me if cryoDRGN is usable here, then help me plan — and, once I confirm, run — the first workflow."

1. Config session. Check for a current configs/site_config.local.md. If absent/stale, offer to run the probe (§2) or ask the user to paste a report from the target server. Never fabricate environment facts.
2. Suitability verdict. Read config_state + rationale; state plainly whether cryoDRGN is ready / partial / blocked / unknown here, citing the report and docs (references/02, references/07).
3. Plan, confirm, then run. Use the capability row (§3) to decide what you may emit: general explanation, labeled placeholder templates, or (when ready) concrete commands with the user's real paths labeled [run-with-confirmation]. On a ready host, after the user explicitly confirms the command and paths, run it; never auto-run on real data.
4. Route to references for detail (§6). Keep within the trust ladder (references/00): live installed CLI (captured) > pinned source/packaging > docs > release notes > papers.

6. Reference index

File	Use it for
references/00_scope_and_trust.md	scope/non-scope, source trust ladder, version pin summary
references/01_source_map.md	exact sources, URLs+fetch dates, commit/tag pins, version drift notes
references/02_config_session_and_environment.md	the config gate, state machine, TTL/staleness, capability table, probe usage
references/03_cli_reference.md	cryodrgn/cryodrgn_utils command namespace (23 + 25), labeled templates
references/04_data_model_and_formats.md	inputs (.mrcs/.star/.cs/.txt), pose/CTF .pkl, outputs (config.yaml, z.pkl, weights.pkl, volumes), 1-indexing
references/05_core_workflows.md	preprocess → parse → backproject sanity → train_vae → analyze → filter → high-res; abinit overview
references/06_interoperability.md	RELION / cryoSPARC import/export, parse_relion, write_star/write_cs
references/07_safety_license_privacy.md	GPLv3, no-install/no-upload boundaries, private-data handling
references/08_validation_and_benchmarks.md	what is/ isn't claimable; papers; quicktest/fixtures (runnable on a ready host after user confirmation)
references/09_troubleshooting.md	missing GPU/cryoDRGN, stale config, broken .star/.cs paths, sign/handedness, indexing
references/10_decision_trees.md	config gate tree; cryoDRGN1-vs-AI; D=128 pilot vs D=256; which parser

7. Provenance

Grounded in pinned cryoDRGN 4.2.1 (PyPI latest captured 2026-06-05; commit 23ae1a3303b1e623f421b816fc7ea426c9d5b580; tag object 2f4db4c02021fd136c53f03a572684921369b268). A beta 4.3.0-b2 exists but is out of scope for this release. Cite sources as in references/01_source_map.md.

Live --help + a GPU smoke run were captured 2026-06-06 on Linux+NVIDIA (a Linux + NVIDIA GPU host) against an installed cryoDRGN 4.2.1 (torch 2.9.1+cu128, cuda True — see _version.txt). Commands in this skill are therefore [VALIDATED: cryoDRGN 4.2.1] and cite the captured help file (e.g. cryodrgn.train_vae.help.txt) where each flag was confirmed. End-to-end smoke results (downsample → parse_pose_star/parse_ctf_star → backproject_voxel → train_vae → analyze) and the ground-truth output layout were recorded in the validation run.