AI Agent Skill for cryoSPARC

What the skill does

The skill is one folder of plain Markdown plus a Python helper. There is no hidden server component and no model-specific glue. It is independent and unofficial; authoritative details remain in the upstream cryoSPARC documentation and license terms.

Install

This unofficial skill ships as part of StructAgent — see the accompanying paper, StructAgent: Orchestrating Cryo-EM Model Building and Refinement with a Multi-Agent LLM System (bioRxiv 2026), for the broader system. The AI agent skill for cryoSPARC itself is self-contained and can be dropped into any coding-agent runtime that can load an instruction file and run shell or Python tools.

Claude Code

$ git clone https://github.com/bhgtiger/StructAgent.git
$ mkdir -p ~/.claude/skills
$ cp -R StructAgent/skills/annika/cryosparc ~/.claude/skills/

Codex CLI / other agent runtimes

Point the runtime at the same folder; the only requirement is that it can read the files on demand and run an approved Python script.

$ cp -R StructAgent/skills/annika/cryosparc <your-agent-skills-dir>/

Resulting layout

cryosparc/
├── README.md                   # install, porting, site-config, safety instructions
├── SKILL.md                    # entrypoint, routing, safety rules
├── lessons.md                  # site/user lessons placeholder
├── references/                 # 32 markdown reference files
└── scripts/
    └── cryosparc_harness.py    # read-only by default; --commit to queue

Configure for your site

The skill becomes useful only after it learns the local deployment. Create a local, non-public site_config.md next to SKILL.md. Do not commit it.

# ~/.claude/skills/cryosparc/site_config.md
# Local file. Do not commit credentials.

## cryoSPARC instance
- master_url:           http://xxx:xxx
- master_version:       v5.x
- license_id:           xxx
- cryosparc_tools_env:  ~/.venvs/cs-tools-v5/bin/python
- default_lane:         xxx

## Access rules
- Read-only inspection first.
- Queue only after explicit user confirmation of project_uid,
  workspace_uid, lane, and params.
- Never store passwords or session tokens here.

Credentials are passed via environment variables at run time, never written into the skill folder:

export CRYOSPARC_HOST='xxx'
export CRYOSPARC_BASE_PORT='xxx'
export CRYOSPARC_EMAIL='xxx@xxx'
read -s CRYOSPARC_PASSWORD
export CRYOSPARC_PASSWORD

Example session

A short happy-path session against project Pxxx, showing the three capabilities back-to-back. The baseline is an existing local-refinement job, J{baseline}. A second scenario below shows the same skill running an entire cryoSPARC → RELION → cryoSPARC classification round-trip from a single instruction.

1. Consult — what parameters did this job change?

2. Check results — read the existing plots

3. Run — rebalance, then redo the local refinement

CryoSPARC - RELION full round trip in one prompt

The session above was three separate questions. This one is the opposite shape: a single instruction, after which the agent runs an entire cryoSPARC → RELION focused 3D classification → cryoSPARC loop on its own — export, classify, map the classes back, rebuild one refinement per class — and pauses exactly once, at the single step that starts compute on the instance. The starting point is a consensus refinement J{src} (~258k particles, box 400 @ xxx Å/px). The question: is one small region of the map fully ordered, or only present in a subset of particles?

Snippets

Connect from Python

import os
from cryosparc.tools import CryoSPARC

cs = CryoSPARC(
    license  = os.environ["CRYOSPARC_LICENSE"],  # xxx-xxx-xxx
    host     = os.environ["CRYOSPARC_HOST"],     # xxx
    base_port= int(os.environ["CRYOSPARC_BASE_PORT"]),  # xxx
    email    = os.environ["CRYOSPARC_EMAIL"],
    password = os.environ["CRYOSPARC_PASSWORD"],
)
assert cs.test_connection()

Inspect a job’s params and assets

project = cs.find_project("Pxxx")
job     = project.find_job("Jxxx")

# Parameters (full dict, including defaults)
params = job.doc["params_spec"]

# Asset listing (PNG / PDF plots, logs, ...)
for asset in job.list_assets():
    print(asset["filename"], asset["_id"])

# Download one asset
job.download_asset(asset_id, "/tmp/out.png")

Queue safely via the harness

# default: dry-run JSON only; no job is queued
$ python scripts/cryosparc_harness.py create-job \
    --project-uid Pxxx --workspace-uid Wxxx \
    --job-type new_local_refine \
    --params-json '{"use_alignment_prior": true}'

# real queue only with explicit commit + queue + lane + confirmation word
$ python scripts/cryosparc_harness.py create-job \
    --project-uid Pxxx --workspace-uid Wxxx \
    --job-type new_local_refine \
    --lane xxx --commit --queue --queue-confirm QUEUE