Guide · Agent skill
How to use the NWB Conversion agent skill (nwb-conversion)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The nwb-conversion skill is a set of instructions and a Python script that lets an AI agent convert a neuroscience recording into a Neurodata Without Borders (NWB) file, the standard archive format for neuroscience data. It covers one specific case: a planar, single-channel two-photon TIFF image stack with frame timestamps, plus a timestamped position CSV. This guide explains what agent skills are, how to install this one, how to ask for it, and what it will and will not do.
NWB Neuroscience ConversionK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the nwb-conversion ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Create the Python 3.12 environment. Run the uv commands in SKILL.md to create nwb-env and install the pinned packages, including both Zarr pins.
- 3Fill in the session JSON. Copy assets/session-template.json beside your raw data and replace every synthetic value with your real metadata, timezone-aware session start, and units.
- 4Confirm clock evidence. Make sure frame timestamps are in reference-clock seconds, and that position data has a shared clock or matched sync pulses.
- 5Ask the agent to convert. Describe your files and goal in plain language, such as converting the TIFF stack and position CSV to NWB and validating it.
- 6Review the validation report. Read the .validation.json with the NWB file and review any Inspector findings and missing metadata before using the data.
What is an agent skill and what does this one make the agent do?
An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a specific kind of task, plus any helper scripts and reference files the task needs. When the skill is installed and your request matches its description, the agent follows its workflow.
With nwb-conversion, the agent inventories your input files and metadata, copies a session template and fills in your real values, checks timing evidence, runs the converter, and reads the validation report. It keeps original metadata and timing intact. It only aligns clocks when you supply matching evidence such as a shared clock or matched synchronization pulses. It does not guess synchronization from signals that merely look coincident.
- Converts a two-photon TIFF image stack and frame timestamps into an acquisition TwoPhotonSeries named Imaging.
- Converts a position CSV with columns time_s, x and y into a behavior Position / SpatialSeries, with coordinates converted to meters.
- Runs schema validation, NWB Inspector checks and round-trip comparisons, and writes a .validation.json report.
- Does not perform spike sorting.
Install the skill from the ZIP or the Claude apps
Download the skill ZIP from this page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/nwb-conversion
- Project install: .claude/skills/nwb-conversion inside your project folder
Set up the tested Python environment
The skill needs Python 3.12 and a set of pinned packages. SKILL.md shows the exact setup using uv, a Python package manager. Run these commands from the skill directory, using the install method in SKILL.md.
Keep both Zarr pins even if your data is HDF5-only. The source reports that NeuroConv 0.10.2 imports its backend configuration modules at startup, and an unconstrained Zarr 3.4.0 installation failed on zarr.codec_registry.
- Required: Python 3.12
- Pinned packages include neuroconv[tiff] 0.10.2, PyNWB 4.2.0, NWB Inspector 0.7.2, roiextractors 0.10.0, tifffile 2026.9.20, zarr 2.18.7 and hdmf-zarr 0.11.3.
- Local HDF5 file access is required. No API keys or accounts are needed.
uv venv --python 3.12 nwb-env
uv pip install --python nwb-env/bin/python 'neuroconv[tiff]==0.10.2' pynwb==4.2.0 \
nwbinspector==0.7.2 roiextractors==0.10.0 tifffile==2026.9.20 \
zarr==2.18.7 hdmf-zarr==0.11.3Prepare your inputs and session metadata
Before converting, the agent needs your real acquisition details. Copy assets/session-template.json beside your raw data and replace its synthetic values. The template is a shape example only; do not keep sample values from it. Paths in the JSON resolve relative to that file.
Timestamps must already be in reference-clock seconds since a timezone-aware session start. The imaging block must set modality to two-photon. Wavelengths are in nanometers. Position coordinates must be in m, cm or mm.
- Frame timestamps: reference-clock seconds since the timezone-aware session start.
- Position CSV header: time_s,x,y.
- Imaging modality must explicitly equal two-photon.
- Wavelengths: nanometers.
- Clock evidence for position: a documented shared clock, or matched synchronization pulses.
Trigger the skill with a natural request
You do not need to name a command. Describe the task and point to your files. Good requests name the file types, the goal (NWB output), and whether you have clock evidence. For example:
- Convert this two-photon TIFF stack and frame_times.csv with the position CSV into an NWB file, and validate it.
- Use the NWB conversion skill to build a session JSON from my metadata and produce an NWB with an Inspector report.
- Synchronize my behavior position CSV to the imaging clock using these three sync pulse pairs, then convert to NWB.
Run the converter and read the results
The agent runs the converter script from the skill directory with your session JSON and an output path. The output must end in .nwb, and the command refuses to overwrite an existing NWB or validation report.
The output includes source and converter checksums, package versions, supplied metadata, units and clock-fit details, in a scratch record and in the validation report. Read the .validation.json next to the NWB file. A passing run does not mean the file is scientifically correct; review Inspector findings in context.
- Schema failures cause the script to exit with an error.
- Critical Inspector findings are flagged for review in the report.
- If an exception occurs during writing, the NWB may be incomplete and has no report; use a fresh output path after fixing the cause.
nwb-env/bin/python scripts/convert_session.py /path/to/session.json --output /path/to/session.nwbKnow the safety notes and limits
The skill runs a Python script on your machine. The source says it uses no network connection during conversion (network is needed only for installation) and needs no credentials. It does not upload or submit anything to an archive.
Position CSV data loads fully into memory, and equality checks load one TIFF frame at a time. For large data, the source notes these trade-offs when adapting the command.
- Runs scripts: yes. Uses network: no.
- No upload or archive submission is part of the workflow.
- Anatomical labels, pulse pairing and calibration still need human review.
What people use it for
- Converting a single-plane two-photon imaging session with frame timestamps into an NWB acquisition TwoPhotonSeries.
- Adding a timestamped behavioral position track (time_s,x,y) to the same NWB file as a Position / SpatialSeries, with coordinates in meters.
- Aligning a position CSV to imaging time using three or more matched sync pulses, with the fitted clock recorded in the report.
- Producing a reproducible conversion with checksums and package versions for a lab or data engineering pipeline.
- Learning how NWB schema validation, NWB Inspector findings and round-trip checks differ.
Frequently asked questions
Is the NWB conversion agent skill free?
The skill is released under the MIT license, as listed on this page. The required Python packages are installed from their own sources, and the source describes no API keys, accounts or credentials for this workflow.
What do I need to install the nwb-conversion skill?
You need Python 3.12, uv, and the pinned packages listed in SKILL.md, including neuroconv[tiff] 0.10.2 and PyNWB 4.2.0. You also need local HDF5 file access. Network access is needed only for installation.
Where do I put the nwb-conversion skill folder?
Place it in ~/.claude/skills/ for a personal install, or in a project's .claude/skills/ folder for one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Can this skill convert SpikeGLX or Open Ephys recordings?
No. The source says SpikeGLX, Open Ephys, multichannel TIFF, volumetric TIFF and compressed video are not tested or decoded by this helper, and each would need its own tests. The skill also does not perform spike sorting.
Why does the skill refuse to align my clocks?
It only synchronizes when you provide real evidence, such as a documented shared clock or matched sync pulses. It never estimates synchronization from coincident-looking signals, because wrong alignment would corrupt the timing.
Does passing validation mean my NWB file is correct?
No. Schema compliance, NWB Inspector findings and data equality answer different questions. The source states that validation cannot confirm anatomical labels, pulse pairing or calibration, so review those yourself.
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 nwb-conversion if you are in a neuroscience lab or data team converting single-plane two-photon imaging with behavioral position tracking into NWB, and you have real clock evidence and want a validation report. Pick a different tool if your recordings come from SpikeGLX, Open Ephys, multichannel or volumetric formats, or if you need spike sorting.
Download the skill