Fmriprep

What it does

When your agent uses it

• The user asks to preprocess fMRI/BOLD data
• Run fMRIPrep on a BIDS dataset
• Set up Docker/Singularity/Apptainer containers for fMRIPrep
• Choose output spaces (MNI152NLin2009cAsym

Example prompts

• “/fmriprep”

Requirements

• Python 3
• Docker

Workflow steps

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

1. 1Output dir == input dir: fMRIPrep will refuse to run. Put derivatives in a separate path (e.g. bids/derivatives/fmriprep-25.2.5/).
2. 2Working directory inside bids_dir: also refused. Put -w /scratch/work outside the input.
3. 3output-spaces MNI152NLin6Asym:res-2 ≠ 2 mm always — res- is a TemplateFlow index, not millimeters. Verify with the template JSON.
4. 4Race conditions on parallel subjects: never share the same -w across subjects. Give each subject its own working directory, or launch each…
5. 5FreeSurfer IsRunning.lh+rh error after a crash: delete IsRunning.* files in /sourcedata/freesurfer/sub-XX/scripts/ and re-run.
6. 6Slice-timing correction is referenced to the middle slice by default (--slice-time-ref 0.5), which shifts effective volume onsets by 0.5…
7. 7Never include all confounds columns in a design matrix — pick a strategy (24P+aCompCor, ICA-AROMA, scrubbing) and use the corresponding…
8. 8No skull-stripped T1w inputs — fMRIPrep expects raw T1w. If skull-stripped, use --skull-strip-t1w skip (understand the risks) or revert to…
9. 9Version pinning: process an entire study with the same fMRIPrep version+container build. Do not upgrade mid-study.
10. 10Datasets with lesions: place sub-XX/anat/sub-XX_label-lesion_roi.nii.gz and add *lesion_roi.nii.gz to .bidsignore — enables lesion…
11. 11Apple Silicon Docker: run under --platform linux/amd64 (or DOCKER_DEFAULT_PLATFORM=linux/amd64 when using fmriprep-docker); the container…
12. 12Multi-echo two-echo data: rejected since 25.2.4 — fMRIPrep requires ≥3 echoes for tedana T2* estimation.

What it can do on your machine

Read from SKILL.md and the folder at commit 93f6855. 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:

  • docker
  • python

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

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • surfer.nmr.mgh.harvard.edu

  Also links to:

  • github.com
  • fmriprep.org
  • doi.org
  • fmriprep.readthedocs.io
  • neurostars.org

  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

Fmriprep loads about 4.1k tokens when it runs, and up to ~41k if it reads all its reference files. Until then it costs about 150 tokens; SKILL.md has 1,308 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~150

When it runs · the whole SKILL.md, loaded when a task matches

~4.1k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~41k

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

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 NeuroAIHub/BrainPilot at commit 93f6855, republished under its AGPL-3.0 licence (© NeuroAIHub). 1,308 words, ~4,119 tokens.

name

fmriprep

description

Preprocess task-based or resting-state fMRI data with fMRIPrep — a robust, BIDS-App preprocessing pipeline built on FSL, ANTs, FreeSurfer, AFNI, and Nilearn. Use this skill whenever the user asks to preprocess fMRI/BOLD data, run fMRIPrep on a BIDS dataset, set up Docker/Singularity/Apptainer containers for fMRIPrep, choose output spaces (MNI152NLin2009cAsym, fsaverage, fsLR/CIFTI), configure susceptibility distortion correction (SDC), extract or interpret the confounds table, resample to surface/grayordinates, cite fMRIPrep and its dependencies, or debug fMRIPrep crashes and hangs.

domain

fmri-neuroimaging

version

1.0.0

authors

Claude (AI-assisted)

review_status

ai-generated

fmriprep <bids_dir> <output_dir> <analysis_level> [OPTIONS]

docker run --rm -it <mounts> nipreps/fmriprep:<version> <bids_dir> <output_dir> participant [OPTIONS]

                       ┌──────────────────────────────────────┐
                       │  BIDS Dataset (T1w/T2w + BOLD + fmap)│
                       └──────────────────┬───────────────────┘
                                          │
                    ┌─────────────────────┼─────────────────────┐
                    ▼                     ▼                     ▼
        ┌───────────────────┐   ┌───────────────────┐   ┌───────────────────┐
        │  Anatomical WF    │   │  Fieldmap WF      │   │  BOLD WF (per run)│
        │  (smriprep)       │   │  (SDCFlows)       │   │  (fmriprep)       │
        │  ───────────────  │   │  ───────────────  │   │  ─────────────    │
        │  • Conform T1w    │   │  • PEPOLAR/TOPUP  │   │  • Reference img  │
        │  • N4 bias corr   │   │  • Phase-diff     │   │  • HMC (mcflirt)  │
        │  • Skull-strip    │   │  • Phase encoding │   │  • STC (3dTShift) │
        │    (antsBrainExt) │   │  • SyN-SDC (t1w)  │   │  • SDC apply      │
        │  • FAST segment   │   │                   │   │  • BBR to T1w     │
        │  • antsRegistrat  │   │                   │   │  • Multi-echo T2* │
        │    → MNI templates│   │                   │   │  • Resample to    │
        │  • recon-all      │   │                   │   │    output spaces  │
        │  • MSM-Sulc       │   │                   │   │  • Surface + CIFTI│
        │  • Curv/Sulc/Thick│   │                   │   │  • Confounds      │
        └─────────┬─────────┘   └──────────┬────────┘   └──────────┬────────┘
                  │                        │                       │
                  └────────────────────────┴───────────────────────┘
                                          │
                                          ▼
                     ┌────────────────────────────────────────┐
                     │  BIDS-Derivatives + sub-XX.html report │
                     └────────────────────────────────────────┘

# 1. Install the wrapper (Python 3.10+)
python -m pip install --user fmriprep-docker

# 2. Get a FreeSurfer license (free): https://surfer.nmr.mgh.harvard.edu/registration.html
#    Save the file, e.g. as ~/.licenses/freesurfer/license.txt
export FS_LICENSE=$HOME/.licenses/freesurfer/license.txt

# 3. Pre-fetch TemplateFlow templates (avoids network needs mid-run)
python -m pip install --user templateflow
python -c "from templateflow.api import get; \
  get(['MNI152NLin2009cAsym','MNI152NLin6Asym','OASIS30ANTs','fsaverage','fsLR'])"

# 4. Run — replace paths with yours
fmriprep-docker /path/to/bids /path/to/derivatives participant \
    --participant-label 01 \
    --output-spaces MNI152NLin2009cAsym:res-2 fsaverage:den-10k \
    --nthreads 8 --omp-nthreads 4 --mem 12000 \
    -w /path/to/work

docker run --rm -it \
    -v /path/to/bids:/data:ro \
    -v /path/to/derivatives:/out \
    -v /path/to/work:/scratch \
    -v $FS_LICENSE:/opt/freesurfer/license.txt:ro \
    -v $HOME/.cache/templateflow:/home/fmriprep/.cache/templateflow \
    nipreps/fmriprep:25.2.5 \
    /data /out participant \
    --participant-label 01 \
    --output-spaces MNI152NLin2009cAsym:res-2 fsaverage:den-10k \
    --nthreads 8 --omp-nthreads 4 --mem 12000 \
    -w /scratch

apptainer run --cleanenv \
    -B /path/to/bids:/data:ro \
    -B /path/to/derivatives:/out \
    -B /path/to/work:/work \
    -B $FS_LICENSE:/opt/freesurfer/license.txt:ro \
    -B $HOME/.cache/templateflow:/opt/templateflow \
    --env TEMPLATEFLOW_HOME=/opt/templateflow \
    fmriprep-25.2.5.sif \
    /data /out participant \
    --participant-label 01 \
    --fs-license-file /opt/freesurfer/license.txt \
    -w /work

fmriprep --version                    # bare-metal
docker run --rm nipreps/fmriprep:25.2.5 --version   # Docker
apptainer run fmriprep-25.2.5.sif --version         # Apptainer

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

Files

SKILL.md and 12 other files (references) in packages/skills/skills/06_fMRI_Neuroimaging/fmriprep of NeuroAIHub/BrainPilot.

• SKILL.md
• references/bids-filter.md
• references/citation.md
• references/cli-reference.md
• references/confounds.md
• references/installation.md
• references/outputs.md
• references/sdc-fieldmaps.md
• references/spaces.md
• references/troubleshooting-faq.md
• references/usage-examples.md
• references/versions-dependencies.md
• references/workflows.md

Open the folder on GitHubat commit 93f6855