@brainpilot/skills 0.0.6 → 0.0.7

package/skills/06_fMRI_Neuroimaging/asl-skill/scripts/compute_cbf.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Compute CBF (Cerebral Blood Flow) maps from ASL perfusion MRI.
+
+Implements the Buxton single-compartment model for pCASL/CASL/PASL
+quantification. Outputs CBF map as NIfTI and optional ROI summary as CSV.
+"""
+import argparse
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+try:
+    import numpy as np
+except ImportError:
+    print("Error: numpy is required.", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    import nibabel as nib
+except ImportError:
+    print("Error: nibabel is required.", file=sys.stderr)
+    sys.exit(1)
+
+# Physical constants
+DEFAULT_PARAMS = {
+    "pcasl": {"alpha": 0.85, "tau": 1.8, "pld": 1.8},
+    "casl": {"alpha": 0.95, "tau": 2.0, "pld": 1.5},
+    "pasl": {"alpha": 0.98, "tau": 0.7, "pld": 1.8},
+}
+
+# T1 of arterial blood (seconds)
+T1B = {1.5: 1.35, 3.0: 1.65, 7.0: 2.1}
+
+# Blood-tissue water partition coefficient (mL/g)
+LAMBDA = 0.9
+
+# Conversion factor: mL/g/s -> mL/100g/min
+CONVERSION = 6000
+
+
+def compute_cbf_pcasl_casl(
+    diff_data: np.ndarray,
+    m0_data: np.ndarray,
+    alpha: float,
+    tau: float,
+    pld: float,
+    t1b: float,
+) -> np.ndarray:
+    """Compute CBF from pCASL/CASL using the Buxton model.
+
+    CBF = (6000 * ΔM * λ) / (2 * α * M0 * T1b * (exp(-w/T1b) - exp(-(τ+w)/T1b)))
+
+    Returns CBF in mL/100g/min.
+    """
+    m0_safe = np.where(m0_data > 0, m0_data, 1.0)
+    numerator = CONVERSION * diff_data * LAMBDA
+    denominator = 2.0 * alpha * m0_safe * t1b * (np.exp(-pld / t1b) - np.exp(-(tau + pld) / t1b))
+
+    cbf = np.where(m0_data > 0, numerator / denominator, 0.0)
+    return cbf
+
+
+def compute_cbf_pasl(
+    diff_data: np.ndarray,
+    m0_data: np.ndarray,
+    alpha: float,
+    ti1: float,
+    ti2: float,
+    t1b: float,
+    bolus_thickness: float = 0.15,
+) -> np.ndarray:
+    """Compute CBF from PASL (QUIPSS II).
+
+    CBF = (6000 * ΔM * λ * TI1) / (2 * α * M0 * T1b * (TI2 - TI1) * exp(-TI2/T1b))
+
+    Returns CBF in mL/100g/min.
+    """
+    m0_safe = np.where(m0_data > 0, m0_data, 1.0)
+    numerator = CONVERSION * diff_data * LAMBDA * ti1
+    denominator = 2.0 * alpha * m0_safe * t1b * (ti2 - ti1) * np.exp(-ti2 / t1b)
+
+    cbf = np.where(m0_data > 0, numerator / denominator, 0.0)
+    return cbf
+
+
+def extract_roi_mean(data: np.ndarray, atlas: np.ndarray, labels: Optional[List[int]] = None) -> Dict[int, float]:
+    """Extract mean CBF for each ROI in the atlas."""
+    unique_labels = np.unique(atlas[atlas > 0]).astype(int)
+    if labels is not None:
+        unique_labels = [l for l in unique_labels if l in labels]
+
+    results = {}
+    for label in unique_labels:
+        mask = atlas == label
+        values = data[mask]
+        values = values[~np.isnan(values)]
+        if len(values) > 0:
+            results[int(label)] = float(np.mean(values))
+    return results
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Compute CBF maps from ASL perfusion MRI."
+    )
+    parser.add_argument("--diff", required=True, help="Path to ASL difference image (control - label)")
+    parser.add_argument("--m0", help="Path to M0 reference image (required for absolute CBF)")
+    parser.add_argument("--output", required=True, help="Output path for CBF map NIfTI")
+    parser.add_argument("--roi-summary", help="Optional: output path for ROI summary CSV")
+    parser.add_argument("--roi-atlas", help="Optional: path to atlas NIfTI for ROI extraction")
+    parser.add_argument("--roi-labels", help="Optional: comma-separated ROI label IDs to extract")
+    parser.add_argument("--label-strategy", default="pcasl", choices=["pcasl", "casl", "pasl"],
+                        help="ASL labeling strategy (default: pcasl)")
+    parser.add_argument("--alpha", type=float, help="Labeling efficiency (overrides default)")
+    parser.add_argument("--tau", type=float, help="Label duration in seconds (overrides default)")
+    parser.add_argument("--pld", type=float, help="Post-labeling delay in seconds (overrides default)")
+    parser.add_argument("--field-strength", type=float, default=3.0, choices=[1.5, 3.0, 7.0],
+                        help="MRI field strength in Tesla (default: 3.0)")
+    parser.add_argument("--no-m0", action="store_true", help="Compute relative CBF without M0 normalization")
+    args = parser.parse_args()
+
+    diff_path = Path(args.diff).resolve()
+    if not diff_path.exists():
+        print(f"Difference image not found: {diff_path}", file=sys.stderr)
+        return 1
+
+    # Load ASL difference image
+    print(f"Loading ASL difference image: {diff_path}")
+    diff_img = nib.load(str(diff_path))
+    diff_data = diff_img.get_fdata()
+    print(f"  Shape: {diff_data.shape}, range: [{diff_data.min():.4f}, {diff_data.max():.4f}]")
+
+    # Load M0
+    m0_data = None
+    if not args.no_m0:
+        if not args.m0:
+            print("[ERROR] --m0 is required for absolute CBF quantification. Use --no-m0 for relative CBF.", file=sys.stderr)
+            return 1
+        m0_path = Path(args.m0).resolve()
+        if not m0_path.exists():
+            print(f"M0 image not found: {m0_path}", file=sys.stderr)
+            return 1
+        m0_img = nib.load(str(m0_path))
+        m0_data = m0_img.get_fdata()
+        print(f"  M0 shape: {m0_data.shape}, range: [{m0_data.min():.4f}, {m0_data.max():.4f}]")
+    else:
+        m0_data = np.ones_like(diff_data)
+        print("  No M0 normalization (relative CBF)")
+
+    # Get quantification parameters
+    strategy = args.label_strategy
+    params = DEFAULT_PARAMS[strategy].copy()
+
+    if args.alpha is not None:
+        params["alpha"] = args.alpha
+    if args.tau is not None:
+        params["tau"] = args.tau
+    if args.pld is not None:
+        params["pld"] = args.pld
+
+    t1b = T1B[args.field_strength]
+
+    print(f"\nCBF Quantification Parameters:")
+    print(f"  Strategy: {strategy}")
+    print(f"  α (labeling efficiency): {params['alpha']}")
+    print(f"  τ (label duration): {params['tau']} s")
+    print(f"  PLD (post-labeling delay): {params['pld']} s")
+    print(f"  T1b (blood T1 at {args.field_strength}T): {t1b} s")
+    print(f"  λ (partition coefficient): {LAMBDA} mL/g")
+
+    # Compute CBF
+    if strategy in ("pcasl", "casl"):
+        cbf_data = compute_cbf_pcasl_casl(
+            diff_data, m0_data,
+            alpha=params["alpha"], tau=params["tau"], pld=params["pld"], t1b=t1b,
+        )
+    else:
+        cbf_data = compute_cbf_pasl(
+            diff_data, m0_data,
+            alpha=params["alpha"], ti1=params["tau"], ti2=params["pld"], t1b=t1b,
+        )
+
+    # Clip negative values
+    cbf_data = np.clip(cbf_data, 0, None)
+
+    # Save CBF map
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    cbf_img = nib.Nifti1Image(cbf_data, diff_img.affine, diff_img.header)
+    nib.save(cbf_img, str(output_path))
+    print(f"\nCBF map saved: {output_path}")
+    print(f"  Range: [{cbf_data.min():.2f}, {cbf_data.max():.2f}] mL/100g/min")
+    print(f"  Mean (non-zero): {cbf_data[cbf_data > 0].mean():.2f} mL/100g/min")
+
+    # ROI extraction
+    if args.roi_atlas and args.roi_summary:
+        atlas_path = Path(args.roi_atlas).resolve()
+        if not atlas_path.exists():
+            print(f"[WARN] Atlas not found: {atlas_path}", file=sys.stderr)
+        else:
+            atlas_img = nib.load(str(atlas_path))
+            atlas_data = atlas_img.get_fdata()
+
+            labels = None
+            if args.roi_labels:
+                labels = [int(l.strip()) for l in args.roi_labels.split(",")]
+
+            roi_values = extract_roi_mean(cbf_data, atlas_data, labels)
+
+            import csv
+            summary_path = Path(args.roi_summary).resolve()
+            summary_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(summary_path, "w", newline="", encoding="utf-8") as f:
+                writer = csv.writer(f)
+                writer.writerow(["roi_label", "mean_cbf_ml_100g_min"])
+                for label, mean_cbf in sorted(roi_values.items()):
+                    writer.writerow([label, f"{mean_cbf:.2f}"])
+            print(f"\nROI summary ({len(roi_values)} ROIs) -> {summary_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/bids-organizer/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: bids-organizer
+description: "Use this skill whenever the user wants to automatically organize raw neuroimaging data (DICOM, NIfTI, EEG, etc.) into a valid BIDS (Brain Imaging Data Structure) dataset. Triggers include: 'organize to BIDS', 'BIDS organizer', 'convert to BIDS', 'BIDS conversion', 'bidsify', 'create BIDS dataset', 'raw data to BIDS', or any request to structure data according to BIDS specification."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: subagent
+skill_type: tool
+dependencies:
+  - dcm2nii
+  - claw-shell
+---
+# BIDS Organizer (Tool Layer)
+
+## Overview
+
+BIDS Organizer is the NeuroClaw interface-layer skill that automatically converts raw or semi-organized neuroimaging data into a standardized BIDS-compliant dataset.
+
+It supports DICOM → NIfTI conversion + BIDS naming, existing NIfTI reorganization, EEG (.set/.edf/.bdf/.fif), and basic metadata handling. The skill generates a clear execution plan, waits for user confirmation, then delegates all heavy work to appropriate base tools.
+
+**Core workflow (never bypassed):**
+1. Scan input directory and detect data types (DICOM, NIfTI, EEG, etc.).
+2. Generate a numbered execution plan with proposed BIDS structure and subject/session labels.
+3. Present the plan, estimated time, and risks; wait for explicit confirmation (“YES” / “execute” / “proceed”).
+4. On confirmation, delegate tasks to `dcm2nii`, `mne-eeg-tool`, and `claw-shell`.
+5. After completion, run BIDS validation and generate a summary report.
+
+**Research use only.**
+
+## Quick Reference
+
+| Task                              | What needs to be done                                      | Delegate to which tool skill          | Expected output                     |
+|-----------------------------------|------------------------------------------------------------|---------------------------------------|-------------------------------------|
+| DICOM to BIDS                     | Convert DICOM → NIfTI + apply BIDS naming                  | `dcm2nii` + `claw-shell`              | BIDS-compliant NIfTI + JSON sidecars|
+| Existing NIfTI to BIDS            | Rename and reorganize NIfTI files into BIDS hierarchy      | `claw-shell`                          | Properly named BIDS dataset         |
+| EEG to BIDS                       | Convert .set/.edf/.bdf/.fif to BIDS EEG format             | `mne-eeg-tool` + `claw-shell`         | BIDS EEG files + events             |
+| Create dataset_description.json   | Generate required BIDS metadata files                      | `claw-shell`                          | dataset_description.json            |
+| Validate BIDS dataset             | Run bids-validator and generate report                     | `claw-shell`                          | validation report                   |
+| Full automatic organization       | End-to-end raw data → valid BIDS dataset                   | All above tools                       | Complete BIDS dataset + QC report   |
+
+## Common Shell Command Examples
+
+```bash
+# DICOM to BIDS (most common)
+dcm2niix -o ./bids/sub-001/ses-01/anat -f "%p_%s" -b y -z y /path/to/dicom/T1
+
+# Validate the resulting BIDS dataset
+bids-validator /path/to/bids_dataset
+```
+
+## Installation (Handled by dependency-planner)
+
+Use `dependency-planner` with requests such as:
+- “Install dcm2niix and bids-validator”
+- “Install MNE-Python for EEG to BIDS conversion”
+
+After installation, verify with:
+```bash
+dcm2niix --version
+bids-validator --version
+```
+
+## NeuroClaw recommended wrapper script
+
+```python
+# bids_organizer_wrapper.py (placed inside the skill folder for reference)
+import subprocess
+from pathlib import Path
+
+def organize_to_bids(raw_dir, bids_dir, subject_id, session_id="01"):
+    bids_dir = Path(bids_dir)
+    bids_dir.mkdir(parents=True, exist_ok=True)
+    
+    # DICOM to BIDS example
+    cmd = [
+        "dcm2niix", "-o", str(bids_dir / f"sub-{subject_id}" / f"ses-{session_id}" / "anat"),
+        "-f", "%p_%s", "-b", "y", "-z", "y", str(raw_dir)
+    ]
+    
+    print("Executing:", " ".join(cmd))
+    subprocess.run(cmd, check=True)
+    
+    # Create basic dataset_description.json
+    desc = {
+        "Name": "NeuroClaw BIDS Dataset",
+        "BIDSVersion": "1.8.0",
+        "DatasetType": "raw"
+    }
+    (bids_dir / "dataset_description.json").write_text(str(desc))
+    
+    print(f"BIDS dataset created at: {bids_dir}")
+```
+
+## Important Notes & Limitations
+
+- This skill only generates the plan and delegates; actual file operations are performed via `claw-shell`.
+- DICOM conversion relies on `dcm2nii`.
+- EEG conversion is delegated to `mne-eeg-tool`.
+- Always review the proposed BIDS structure (subject/session labels, run numbers) before confirmation.
+- Large datasets may require significant disk space and time.
+
+## When to Call This Skill
+
+- Raw scanner data (DICOM) needs to be converted and organized into BIDS
+- Existing NIfTI/EEG files need proper BIDS naming and folder structure
+- Preparing data for `fmriprep-tool`, `hcppipeline-tool`, `fsl-tool`, or `fmri-skill`
+- Before running any standardized preprocessing pipeline
+
+## Benchmark-Facing Default Mainline
+
+For benchmark-style BIDS organization tasks, do not expand into a generic all-modality organizer unless the task explicitly asks for that breadth.
+
+- First identify the narrow target modality and output contract.
+- Reuse only the BIDS pieces needed for that target modality.
+- Do not pull in EEG branches, full multi-modality survey logic, or large wrapper orchestration when the task is only asking for one narrow anatomical or diffusion path.
+- Do not treat the interactive confirmation-heavy core workflow as mandatory for benchmark tasks that explicitly ask for direct completion. In benchmark mode, the answer should default to the narrow executable organization path instead of plan-first / confirm-first orchestration.
+- Do not make large review buckets such as `misc_nonbids_review/`, broad unresolved-item triage systems, or generic catch-all wrappers the center of the answer unless the prompt explicitly asks for audit/review handling.
+- If the task is specifically structural MRI organization, keep the answer centered on:
+    - DICOM to NIfTI conversion only if needed,
+    - `sub-*/[ses-*/]anat/` placement,
+    - valid suffix naming such as `T1w`, `T2w`, `FLAIR`,
+    - required top-level files like `dataset_description.json`,
+    - validator/report output.
+- If the task is diffusion-only, keep the answer centered on `dwi/` organization and diffusion sidecars instead of broadening into whole-dataset BIDS strategy.
+- If subject/session/modality cannot be inferred reliably, report the blocked item explicitly instead of widening into a generic heuristic-heavy organizer.
+
+### Direct Mixed-Modality Benchmark Path
+
+When the benchmark task asks for automatic organization of local DICOM/NIfTI/EEG raw data into BIDS, but does not ask for an interactive planner, default to this narrow path:
+
+1. scan only for the modalities explicitly mentioned by the task,
+2. organize those modalities into the required BIDS hierarchy,
+3. generate the minimal required dataset metadata,
+4. run validation and report concrete blockers,
+5. stop there.
+
+Do not turn this into a reusable platform-style organizer with review zones, broad plugin branches, or full modality-by-modality expansion unless the prompt explicitly asks for that breadth.
+
+### Existing DWI NIfTI Sidecar Path
+
+When the task already provides DWI `NIfTI + bval + bvec` files, the preferred mainline is:
+
+1. detect valid DWI image / sidecar triplets,
+2. infer `sub-`, optional `ses-`, and optional `run-` entities,
+3. place outputs under `sub-*/[ses-*/]dwi/`,
+4. preserve matching `.bval`, `.bvec`, and optional `.json`,
+5. generate minimal dataset metadata and validate.
+
+In this situation, do not broaden the answer into DICOM conversion, EEG conversion, or a whole-dataset mixed-modality organizer unless the prompt explicitly asks for those branches.
+
+### Structural MRI Narrow Path
+
+For narrow structural MRI BIDS tasks, the preferred mainline is:
+
+1. detect whether input is DICOM or existing NIfTI,
+2. convert with `dcm2niix` only when needed,
+3. place outputs under `sub-*/[ses-*/]anat/`,
+4. assign only the correct structural suffixes,
+5. generate minimal required dataset metadata,
+6. run BIDS validation and summarize unmapped files.
+
+Do not replace that mainline with a broader all-modality organizer unless the prompt explicitly requests a full mixed-modality BIDS conversion.
+
+## Post-Execution Verification (Harness Integration)
+
+After BIDS organization 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="bids_organization")
+
+# 1. BIDS structure compliance
+verifier.add_check("bids_structure", 
+    checker=lambda: verify_bids_structure(bids_dir),
+    severity="error"
+)
+
+# 2. Dataset description file
+verifier.add_check("dataset_description",
+    checker=lambda: verify_dataset_description_exists(bids_dir),
+    severity="error"
+)
+
+# 3. Subject/session naming convention
+verifier.add_check("naming_convention",
+    checker=lambda: verify_bids_naming(bids_dir),
+    severity="error"
+)
+
+# 4. Metadata JSON sidecar completeness
+verifier.add_check("json_sidecars",
+    checker=lambda: verify_json_sidecars(bids_dir),
+    severity="warning"
+)
+
+# 5. Required BIDS files presence
+verifier.add_check("required_files",
+    checker=lambda: verify_required_files(bids_dir),
+    severity="error"
+)
+
+report = verifier.run(bids_dir)
+
+# Log verification results
+logger = AuditLogger(log_file=f"{bids_dir}/bids_verification.jsonl")
+logger.log_validation(
+    task_name="bids_organization",
+    checks_passed=len([r for r in report.results if r.passed]),
+    checks_failed=len([r for r in report.results if not r.passed]),
+    warnings=len([r for r in report.results if r.severity == "warning" and not r.passed]),
+    report_summary=report.to_dict()
+)
+
+if report.failed:
+    raise ValueError(f"BIDS verification failed: {report.summary}")
+```
+
+**Output files generated**:
+- `{bids_dir}/bids_verification.jsonl` — structured audit log
+- `{bids_dir}/.bids_validation_timestamp` — verification completion marker
+
+## Complementary / Related Skills
+
+- `dependency-planner` → install required tools
+- `claw-shell` → safe execution of all commands
+- `harness-core` → automated verification and audit logging
+
+## More Advanced Features
+
+For complex BIDS cases (multi-session, multi-run, custom metadata, HEUDICONV heuristics, etc.), please refer to the official BIDS specification:
+
+- Official BIDS Website: https://bids.neuroimaging.io/
+- BIDS Specification: https://bids-specification.readthedocs.io/
+
+You may use the `multi-search-engine` or `academic-research-hub` skill to find the latest BIDS conversion best practices.
+
+---
+Created At: 2026-03-25 16:00 HKT  
+Last Updated At: 2026-04-05 02:01 HKT
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/bold5000-skill/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: bold5000-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the BOLD5000 dataset, including download, BIDS organization, and processing of task-fMRI data with visual image stimuli. Triggers include: 'BOLD5000', 'BOLD 5000', 'process BOLD5000', 'visual fMRI', or any request to run the BOLD5000 pipeline. This is the NeuroClaw dataset-orchestration layer for BOLD5000."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - smri-skill
+  - fmri-skill
+  - bids-organizer
+  - claw-shell
+---
+# BOLD5000 Skill (Dataset-Orchestration Layer)
+
+## Overview
+`bold5000-skill` is the NeuroClaw orchestration skill for the **BOLD5000** dataset.
+
+BOLD5000 is a high-density repeated visual fMRI dataset with 8 participants performing 5,000-image visual recognition tasks. It is designed for studying visual object recognition and scene understanding.
+
+It coordinates a fixed three-phase workflow:
+1. Download BOLD5000 data from the OpenNeuro repository.
+2. Prepare and validate BIDS-style data organization for downstream processing.
+3. Delegate modality pipelines to `smri-skill` and `fmri-skill`.
+
+This skill follows NeuroClaw hierarchy:
+- Defines **WHAT to do**, not low-level implementation details.
+- Does **not** execute direct shell commands itself.
+- Delegates all execution via `claw-shell` to base/tool skills.
+
+**Research use only.**
+
+---
+
+## Download Stage (Mandatory First Step)
+
+### Source
+BOLD5000 data is available on OpenNeuro:
+- Website: https://bold5000-dataset.github.io/
+- OpenNeuro: https://openneuro.org/datasets/ds002785
+
+### Supported BOLD5000 Data Packages
+- **Imaging data**: T1w structural, task-fMRI (NIfTI format)
+- **Stimulus data**: 5,000 natural images with category labels and image metadata
+- **Behavioral data**: Recognition memory judgments, response times
+- **Participants**: 4 participants x ~1250 images each (high-density repeated measures)
+
+### Delegation Rules for Download
+- Environment/setup checks: `dependency-planner` + `conda-env-manager`
+- OpenNeuro dataset download: `claw-shell` (via `openneuro` CLI or `datalad`)
+- Optional raw-data organization to BIDS-style staging: `bids-organizer`
+
+### Download Inputs to Confirm in Plan
+- Target subset (all subjects, specific subjects)
+- Whether to include stimulus images
+- Destination directory with sufficient disk space
+
+---
+
+## Narrow Path: BOLD5000 Raw NIfTI -> BIDS Staging
+
+Use this path when the task only asks to reorganize raw BOLD5000 NIfTI files into a BIDS-style dataset and does not require preprocessing or downstream analysis.
+
+### Expected narrow-path behavior
+1. BOLD5000 data from OpenNeuro is already in BIDS format; verify and validate structure.
+2. Route modalities:
+   - T1w -> `anat/*_T1w`
+   - task-fMRI -> `func/*_task-*_bold`
+3. Preserve stimulus metadata and event files.
+4. Emit dataset-level outputs such as `dataset_description.json`, `participants.tsv`.
+
+---
+
+## Core Workflow (Never Bypassed)
+1. Identify user target: download, BIDS staging, or full preprocessing.
+2. Generate a numbered plan with tools, outputs, runtime, storage, and risks.
+3. Wait for explicit confirmation (`YES` / `execute` / `proceed`).
+4. On confirmation, run download stage first (if needed).
+5. After download success, verify/prepare BIDS staging using `scripts/reorganize_bold5000.py`.
+6. Delegate to modality skills:
+   - `smri-skill` for structural MRI (T1w)
+   - `fmri-skill` for task-fMRI
+7. If stimulus analysis is requested, use `scripts/extract_bold5000_stimulus.py` to generate stimulus metadata.
+8. Save outputs into a BOLD5000-centered structure under `bold5000_output/`.
+
+---
+
+## Stimulus Metadata Extraction
+
+### Script: `scripts/extract_bold5000_stimulus.py`
+
+Extracts and organizes BOLD5000 stimulus metadata for downstream analysis.
+
+```bash
+python skills/bold5000-skill/scripts/extract_bold5000_stimulus.py \
+  --stimulus-dir /path/to/bold5000_raw/stimuli \
+  --output /path/to/bold5000_output/stimulus/stimulus_metadata.csv
+```
+
+Features:
+- Reads stimulus image file names and paths
+- Extracts category labels (object, scene, etc.)
+- Generates per-image metadata CSV for modeling
+- Links stimulus presentation events to fMRI volumes
+
+---
+
+## QC Integration
+
+### Script: `scripts/bold5000_qc_summary.py`
+
+```bash
+python skills/bold5000-skill/scripts/bold5000_qc_summary.py \
+  --fmriprep-dir /path/to/bold5000_output/fmriprep \
+  --output /path/to/bold5000_output/qc/qc_summary.csv \
+  --fd-threshold 0.3
+```
+
+---
+
+## Recommended Output Layout
+All assets should be organized under `./bold5000_output/`:
+- `bold5000_output/raw/` (downloaded original BOLD5000 files)
+- `bold5000_output/bids/` (BIDS data)
+- `bold5000_output/smri/` (links or copies from `smri_output/`)
+- `bold5000_output/fmri/` (links or copies from `fmri_output/`)
+- `bold5000_output/stimulus/` (stimulus metadata and event files)
+- `bold5000_output/qc/` (QC summaries)
+- `bold5000_output/logs/` (download + orchestration logs)
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full `download -> staging -> multimodal processing` orchestration when the task is only asking for local BOLD5000 data staging or organization.
+
+- If the task starts from raw BOLD5000 data already present on disk and only asks for BIDS-style staging / validation:
+  - skip the mandatory download stage
+  - default to the narrow path `local raw BOLD5000 discovery -> BIDS validation -> minimal metadata -> report`
+- In benchmark mode, do not require explicit confirmation before presenting the direct staging solution.
+
+---
+
+## Safety and Execution Policy
+- No execution before explicit plan confirmation.
+- All execution must be routed via `claw-shell`.
+- Missing dependencies must be resolved by `dependency-planner` before running.
+
+---
+
+## Important Notes and Limitations
+- BOLD5000 is a small dataset (4 participants); statistical power is limited for group-level analyses.
+- BOLD5000 uses high-density repeated image presentations; analysis requires handling of repeated measures.
+- BOLD5000 data from OpenNeuro is already in BIDS format; re-staging may not be needed.
+- Stimulus images are included in the dataset; event files reference image file names.
+- `bold5000-skill` is orchestration-only; detailed preprocessing logic remains in `smri-skill` and `fmri-skill`.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end BOLD5000 workflow.
+- User asks to download BOLD5000 data and then run task-fMRI processing.
+- User needs BIDS validation for BOLD5000 data.
+- User asks to extract BOLD5000 stimulus metadata.
+- User needs BOLD5000-specific QC summaries.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill`
+- `fmri-skill`
+- `bids-organizer`
+- `fmriprep-tool`
+- `dependency-planner`
+- `conda-env-manager`
+- `claw-shell`
+
+---
+
+## Reference
+- BOLD5000: https://bold5000-dataset.github.io/
+- Chang et al., 2019, *BOLD5000: A public fMRI dataset of 5,000 images*
+- BIDS spec: https://bids.neuroimaging.io/
+
+Created At: 2026-05-06 01:52 HKT
+Last Updated At: 2026-05-06 01:52 HKT
+Author: chengwang96