git:20260506.86420c0 to git:20261014.f405841

- description: "Use this skill whenever the user wants to process structural MRI data (T1w, T2w, FLAIR, etc.) with FreeSurfer, especially for cortical/subcortical segmentation, surface reconstruction, parcellation, cortical thickness, volume statistics, or full recon-all pipeline. Triggers include: 'freesurfer', 'recon-all', 'segment MRI', 'FreeSurfer processing', 'cortical segmentation', 'subcortical segmentation', 'run recon-all', 'freesurfer T1', 'process brain MRI with freesurfer', 'aseg aparc', or any request to run FreeSurfer on NIfTI MRI data for research analysis."

- license: MIT License (NeuroClaw custom skill – freely modifiable within the project)

- ## Overview

-

- FreeSurfer is the gold-standard open-source suite for automated reconstruction of the brain’s cortical surface from structural MRI, including skull-stripping, intensity normalization, Talairach registration, cortical parcellation (Desikan-Killiany / Destrieux atlases), subcortical segmentation (`aseg`), surface mesh generation, cortical thickness estimation, and statistics.

-

- This skill serves as the **NeuroClaw interface-layer wrapper** for FreeSurfer and strictly follows the hierarchical design:

-

- 1. Check whether FreeSurfer is installed (`recon-all --version`, `$FREESURFER_HOME` environment variable).

- 2. If not found → immediately invoke `dependency-planner` to plan and (after user confirmation) install the latest stable FreeSurfer release + license setup.

- 3. Collect and confirm: input NIfTI file(s), subject ID, output `SUBJECTS_DIR`, desired stages/flags (e.g. `-all`, `-autorecon1..3`, `-T2`, `-FLAIR`, `-parallel`).

- 4. Generate a clear, numbered execution plan including exact shell commands.

- 5. Present plan, estimated runtime, disk/RAM requirements, and risks → wait for explicit user confirmation (“YES” / “execute” / “proceed”).

- 6. On confirmation → delegate **all** shell command execution to the `claw-shell` skill (environment setup, `recon-all` invocation, logging, progress monitoring).

- 7. Report completion status, log location, output directory, and next steps.

-

- **Key design principle (2026 update)**: No direct `subprocess.run()` calls for long-running FreeSurfer commands. All shell execution is routed through `claw-shell` for centralized logging, timeout handling, real-time output streaming, and interruption safety.

-

- **Research use only.**

-

- ## Quick Reference (Common Use Cases)

-

- | Task | Recommended `recon-all` flags / approach |

- |-----------------------------------|-------------------------------------------------------------------|

- | Full pipeline (most common) | `-all` |

- | Fast subcortical + basic surfaces | `-autorecon1 -autorecon2 -autorecon3` |

- | Cortical surfaces & parcellation | `-autorecon2 -autorecon3` (after `autorecon1` completed) |

- | Improve pial surface with T2 | `-T2 T2w.nii.gz` |

- | Use FLAIR for better segmentation | `-FLAIR FLAIR.nii.gz` |

- | Enable multi-core acceleration | `-parallel -openmp 8` (or match available cores) |

- | Resume interrupted run | Omit `-i` and `-all`, specify stages only |

- | Generate statistics only | `-stats` |

-

- ## Installation Check & Setup

-

- Installation is **fully delegated** to `dependency-planner`.

-

- When FreeSurfer is not detected:

- - Call `dependency-planner` with request:

- "Install latest stable FreeSurfer (8.1.0 or newer) on current OS, including license.txt setup"

- - After user confirms the installation plan → `dependency-planner` handles download, package install, license placement

- - This skill then verifies `$FREESURFER_HOME` and `recon-all` availability

- **Prerequisites**:

- - `dependency-planner` (mandatory for installation)

- - `claw-shell` (mandatory for command execution)

- - Valid FreeSurfer academic license (free registration required)

- - ≥16 GB RAM recommended (32 GB+ strongly preferred for `-all`)

- ## Agent Reference Rule

- When the agent needs FreeSurfer processing implementation code, it should first consult the curated snippet in `skills/freesurfer-tool/scripts/` instead of copying from the embedded wrapper below.

- Reference snippet available:

- - `scripts/freesurfer_processor.py` -> recon-all pipeline orchestration: environment setup, stage selection, parallel flags, claw-shell delegation

- Example:

- python skills/freesurfer-tool/scripts/freesurfer_processor.py \

- --input-mri sub-001_T1w.nii.gz \

- --subjid sub-001 \

- --subjects-dir /data/freesurfer_output \

- --stages all \

- --extra-flags "-T2 T2.nii.gz -parallel -openmp 12"

- ```

-

- ## NeuroClaw recommended wrapper script

-

- ```python

- # freesurfer_processor.py

- import argparse

- import os

- import sys

- from pathlib import Path

- from datetime import datetime

-

- # In real NeuroClaw: these would be agent tool calls

- def check_freesurfer_installed():

- # Simulate check via claw-shell

- # Real impl: call claw-shell with "recon-all --version"

- return False, "FreeSurfer not found (simulation mode)"

-

- def delegate_to_claw_shell(commands, purpose, log_tag):

- print(f"[Delegating to claw-shell] Purpose: {purpose}")

- print(f"Log tag: {log_tag}")

- print("Commands to execute:")

- for cmd in commands:

- print(" " + cmd)

- # Real implementation: agent/tool call to claw-shell

- # e.g. tool_call("claw-shell", commands=commands, log_tag=log_tag, capture_output=True, timeout="24h")

-

- def main():

- parser = argparse.ArgumentParser(description="NeuroClaw FreeSurfer Processor")

- parser.add_argument("--input-mri", required=True, help="Path to T1w (or other) NIfTI file")

- parser.add_argument("--subjid", required=True, help="Subject ID (e.g. sub-001)")

- parser.add_argument("--subjects-dir", required=True, help="Output SUBJECTS_DIR path")

- parser.add_argument("--stages", default="all", help="all / autorecon1 / autorecon2 / autorecon3 / stats / comma-separated stages")

- parser.add_argument("--extra-flags", default="", help="Additional flags, e.g. '-T2 T2.nii.gz -FLAIR FLAIR.nii.gz -parallel -openmp 12'")

- parser.add_argument("--plan-only", action="store_true", help="Show plan without execution")

- args = parser.parse_args()

-

- installed, version_info = check_freesurfer_installed()

- if not installed:

- print("FreeSurfer not detected on system.")

- print("→ Invoking dependency-planner to install FreeSurfer and set up license.")

- print("Please complete the dependency-planner confirmation flow first.")

- sys.exit(1)

-

- print("FreeSurfer detected:", version_info)

-

- subjects_dir = Path(args.subjects_dir).resolve()

- print(f"\nProcessing plan for subject: {args.subjid}")

- print(f"Input MRI : {args.input_mri}")

- print(f"Output dir : {subjects_dir}")

- print(f"Stages : {args.stages}")

- if args.extra_flags:

- print(f"Extra flags : {args.extra_flags}")

-

- # Build shell commands

- commands = []

- # 1. Set environment

- fs_home = "/usr/local/freesurfer" # typical default; adjust if needed

- commands.append(f"export FREESURFER_HOME={fs_home}")

- commands.append(f"source $FREESURFER_HOME/SetUpFreeSurfer.sh")

-

- # 2. recon-all command

- recon_cmd = [

- "recon-all",

- "-subjid", args.subjid,

- "-i", args.input_mri

- ]

-

- if args.stages == "all":

- recon_cmd.append("-all")

- elif "," in args.stages:

- for stage in args.stages.split(","):

- stage = stage.strip()

- if stage:

- recon_cmd.append(f"-{stage}")

- else:

- recon_cmd.append(f"-{args.stages}")

-

- if args.extra_flags:

- recon_cmd.extend(args.extra_flags.split())

-

- # Recommend parallel execution if not disabled

- if "-parallel" not in args.extra_flags and "-openmp" not in args.extra_flags:

- recon_cmd.extend(["-parallel", "-openmp", "8"])

-

- commands.append(" ".join(recon_cmd))

-

- log_tag = f"freesurfer_{args.subjid}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"

-

- print("\nExecution plan (to be run via claw-shell):")

- for i, cmd in enumerate(commands, 1):

- print(f"Step {i}: {cmd}")

-

- print(f"\nEstimated runtime: 4–24 hours (full -all), 1–4 hours (segmentation stages only)")

- print(f"Disk usage: ~2–5 GB per subject")

- print(f"Logs will be captured by claw-shell under tag: {log_tag}")

-

- if args.plan_only:

- print("\nPlan-only mode — no execution performed.")

- return

-

- confirm = input("\nExecute now? Type YES to proceed: ").strip().upper()

- if confirm != "YES":

- print("Aborted by user.")

- return

-

- print("\nDelegating pipeline execution to claw-shell skill...")

- delegate_to_claw_shell(

- commands=commands,

- purpose=f"FreeSurfer processing for subject {args.subjid} ({args.stages})",

- log_tag=log_tag

- )

-

- print(f"→ Execution handed over to claw-shell.")

- print(f"→ Check logs using tag: {log_tag}")

- print(f"→ Final outputs will be in: {subjects_dir / args.subjid}")

-

- if __name__ == "__main__":

- main()

- ## Important Notes & Limitations

-

- - All actual shell command execution is delegated to `claw-shell` (no direct `subprocess` calls for `recon-all`).

- - Full `-all` pipeline is very long-running → `claw-shell` should support background/detached mode or long timeouts.

- - Input must be NIfTI (`.nii` or `.nii.gz`); convert DICOM first using `dcm2nii` skill.

- - Output follows standard FreeSurfer structure: `$SUBJECTS_DIR/<subjid>`.

- - Windows users: strongly recommended to use WSL2 (installation handled by `dependency-planner`).

- - License check: skill assumes `license.txt` is already in place after `dependency-planner` run.

-

- ## When to Call This Skill

-

- - User provides structural MRI (NIfTI) and wants automated FreeSurfer processing.

- - Any mention of `recon-all`, `aseg`, `aparc`, cortical thickness, surface reconstruction, or FreeSurfer statistics.

-

- ## Complementary / Related Skills

-

- - `dependency-planner` → install FreeSurfer + license

- - `claw-shell` → safe execution of long-running shell commands

- - `conda-env-manager` → manage Python environment for post-processing FreeSurfer outputs

-

- ## Reference

-

- Official site: https://surfer.nmr.mgh.harvard.edu

- Latest stable release (as of 2026): FreeSurfer 8.1.0 or newer

- License registration: https://surfer.nmr.mgh.harvard.edu/registration.html

- Documentation: https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferWiki

-

- Custom NeuroClaw skill created to integrate FreeSurfer safely into the hierarchical skill structure.

-

- Curated reference snippet in this skill:

- - `skills/freesurfer-tool/scripts/freesurfer_processor.py`

-

- ## Post-Execution Verification (Harness Integration)

-

- After FreeSurfer processing completes, this skill **automatically invokes harness-core's VerificationRunner** to validate output integrity:

-

- **Integrated verification checks**:

-

- ```python

- from skills.harness_core import VerificationRunner, AuditLogger

-

- verifier = VerificationRunner(task_type="freesurfer_processing")

- # 1. Brain-extracted anatomy files

- verifier.add_check("brain_extraction",

- checker=lambda: verify_brain_extraction(subjects_dir, subjid),

- severity="error"

- )

- # 2. Cortical surface files (white, pial)

- verifier.add_check("surface_reconstruction",

- checker=lambda: verify_surface_files(subjects_dir, subjid),

- severity="error"

- )

- # 3. Cortical thickness bounds (1–4 mm range)

- verifier.add_check("thickness_bounds",

- checker=lambda: verify_cortical_thickness_range(subjects_dir, subjid),

- severity="warning"

- )

- # 4. parcellation labels (aparc/aseg)

- verifier.add_check("parcellation",

- checker=lambda: verify_aparc_aseg(subjects_dir, subjid),

- severity="error"

- )

- # 5. Statistics file completeness

- verifier.add_check("statistics",

- checker=lambda: verify_stats_files(subjects_dir, subjid),

- severity="warning"

- )

- report = verifier.run(subjects_dir)

- # Log verification results

- logger = AuditLogger(log_file=f"{subjects_dir}/{subjid}/freesurfer_verification.jsonl")

- logger.log_validation(

- task_name="freesurfer_processing",

- subject_id=subjid,

- checks_passed=len([r for r in report.results if r.passed]),

- total_checks=len(report.results)

- )

- ```

- **Output**: `{SUBJECTS_DIR}/{subjid}/freesurfer_verification.jsonl` (structured audit log with JSONL format)

- ---

- Created At: 2026-03-19 20:00 HKT

- Last Updated At: 2026-04-05 02:03 HKT

- Author: chengwang96