pi-skill-search 0.1.0

package/skills/pufferlib/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: pufferlib
+description: High-performance reinforcement learning framework optimized for speed and scale. Use when you need fast parallel training, vectorized environments, multi-agent systems, or integration with game environments (Atari, Procgen, NetHack). Achieves 2-10x speedups over standard implementations. For quick prototyping or standard algorithm implementations with extensive documentation, use stable-baselines3 instead.
+---
+
+# PufferLib - High-Performance Reinforcement Learning
+
+## Overview
+
+PufferLib is a high-performance reinforcement learning library designed for fast parallel environment simulation and training. It achieves training at millions of steps per second through optimized vectorization, native multi-agent support, and efficient PPO implementation (PuffeRL). The library provides the Ocean suite of 20+ environments and seamless integration with Gymnasium, PettingZoo, and specialized RL frameworks.
+
+## When to Use This Skill
+
+Use this skill when:
+- **Training RL agents** with PPO on any environment (single or multi-agent)
+- **Creating custom environments** using the PufferEnv API
+- **Optimizing performance** for parallel environment simulation (vectorization)
+- **Integrating existing environments** from Gymnasium, PettingZoo, Atari, Procgen, etc.
+- **Developing policies** with CNN, LSTM, or custom architectures
+- **Scaling RL** to millions of steps per second for faster experimentation
+- **Multi-agent RL** with native multi-agent environment support
+
+## Core Capabilities
+
+### 1. High-Performance Training (PuffeRL)
+
+PuffeRL is PufferLib's optimized PPO+LSTM training algorithm achieving 1M-4M steps/second.
+
+**Quick start training:**
+```bash
+# CLI training
+puffer train procgen-coinrun --train.device cuda --train.learning-rate 3e-4
+
+# Distributed training
+torchrun --nproc_per_node=4 train.py
+```
+
+**Python training loop:**
+```python
+import pufferlib
+from pufferlib import PuffeRL
+
+# Create vectorized environment
+env = pufferlib.make('procgen-coinrun', num_envs=256)
+
+# Create trainer
+trainer = PuffeRL(
+    env=env,
+    policy=my_policy,
+    device='cuda',
+    learning_rate=3e-4,
+    batch_size=32768
+)
+
+# Training loop
+for iteration in range(num_iterations):
+    trainer.evaluate()  # Collect rollouts
+    trainer.train()     # Train on batch
+    trainer.mean_and_log()  # Log results
+```
+
+**For comprehensive training guidance**, read `(see docs)` for:
+- Complete training workflow and CLI options
+- Hyperparameter tuning with Protein
+- Distributed multi-GPU/multi-node training
+- Logger integration (Weights & Biases, Neptune)
+- Checkpointing and resume training
+- Performance optimization tips
+- Curriculum learning patterns
+
+### 2. Environment Development (PufferEnv)
+
+Create custom high-performance environments with the PufferEnv API.
+
+**Basic environment structure:**
+```python
+import numpy as np
+from pufferlib import PufferEnv
+
+class MyEnvironment(PufferEnv):
+    def __init__(self, buf=None):
+        super().__init__(buf)
+
+        # Define spaces
+        self.observation_space = self.make_space((4,))
+
+### 3. Vectorization and Performance
+
+Achieve maximum throughput with optimized parallel simulation.
+
+**Vectorization setup:**
+```python
+import pufferlib
+
+# Automatic vectorization
+env = pufferlib.make('environment_name', num_envs=256, num_workers=8)
+
+# Performance benchmarks:
+# - Pure Python envs: 100k-500k SPS
+# - C-based envs: 100M+ SPS
+# - With training: 400k-4M total SPS
+
+

package/skills/pydeseq2/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: pydeseq2
+description: Differential gene expression analysis (Python DESeq2). Identify DE genes from bulk RNA-seq counts, Wald tests, FDR correction, volcano/MA plots, for RNA-seq analysis.
+---
+
+# PyDESeq2
+
+## Overview
+
+PyDESeq2 is a Python implementation of DESeq2 for differential expression analysis with bulk RNA-seq data. Design and execute complete workflows from data loading through result interpretation, including single-factor and multi-factor designs, Wald tests with multiple testing correction, optional apeGLM shrinkage, and integration with pandas and AnnData.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Analyzing bulk RNA-seq count data for differential expression
+- Comparing gene expression between experimental conditions (e.g., treated vs control)
+- Performing multi-factor designs accounting for batch effects or covariates
+- Converting R-based DESeq2 workflows to Python
+- Integrating differential expression analysis into Python-based pipelines
+- Users mention "DESeq2", "differential expression", "RNA-seq analysis", or "PyDESeq2"
+
+## Quick Start Workflow
+
+For users who want to perform a standard differential expression analysis:
+
+```python
+import pandas as pd
+from pydeseq2.dds import DeseqDataSet
+from pydeseq2.ds import DeseqStats
+
+# 1. Load data
+counts_df = pd.read_csv("counts.csv", index_col=0).T  # Transpose to samples × genes
+metadata = pd.read_csv("metadata.csv", index_col=0)
+
+# 2. Filter low-count genes
+genes_to_keep = counts_df.columns[counts_df.sum(axis=0) >= 10]
+counts_df = counts_df[genes_to_keep]
+
+# 3. Initialize and fit DESeq2
+dds = DeseqDataSet(
+    counts=counts_df,
+    metadata=metadata,
+    design="~condition",
+    refit_cooks=True
+)
+dds.deseq2()
+
+# 4. Perform statistical testing
+ds = DeseqStats(dds, contrast=["condition", "treated", "control"])
+ds.summary()
+
+# 5. Access results
+results = ds.results_df
+significant = results[results.padj < 0.05]
+print(f"Found {len(significant)} significant genes")
+```
+
+## Core Workflow Steps
+
+### Step 1: Data Preparation
+
+**Input requirements:**
+- **Count matrix:** Samples × genes DataFrame with non-negative integer read counts
+- **Metadata:** Samples × variables DataFrame with experimental factors
+
+**Common data loading patterns:**
+
+```python
+# From TSV
+counts_df = pd.read_csv("counts.tsv", sep="\t", index_col=0).T
+
+# From AnnData
+import anndata as ad
+adata = ad.read_h5ad("data.h5ad")
+counts_df = pd.DataFrame(adata.X, index=adata.obs_names, columns=adata.var_names)
+metadata = adata.obs
+```
+
+**Data filtering:**
+
+```python
+# Remove low-count genes
+genes_to_keep = counts_df.columns[counts_df.sum(axis=0) >= 10]
+counts_df = counts_df[genes_to_keep]
+
+# Remove samples with missing metadata
+samples_to_keep = ~metadata.condition.isna()
+counts_df = counts_df.loc[samples_to_keep]
+metadata = metadata.loc[samples_to_keep]
+```
+
+### Step 2: Design Specification
+
+The design formula specifies how gene expression is modeled.
+
+**Single-factor designs:**
+```python
+design = "~condition"  # Simple two-group comparison
+```
+
+**Multi-factor designs:**
+```python
+design = "~batch + condition"  # Control for batch effects
+design = "~age + condition"     # Include continuous covariate
+design = "~group + condition + group:condition"  # Interaction effects
+```

package/skills/pydicom/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: pydicom
+description: Python library for working with DICOM (Digital Imaging and Communications in Medicine) files. Use this skill when reading, writing, or modifying medical imaging data in DICOM format, extracting pixel data from medical images (CT, MRI, X-ray, ultrasound), anonymizing DICOM files, working with DICOM metadata and tags, converting DICOM images to other formats, handling compressed DICOM data, or processing medical imaging datasets. Applies to tasks involving medical image analysis, PACS systems, radiology workflows, and healthcare imaging applications.
+---
+
+# Pydicom
+
+## Overview
+
+Pydicom is a pure Python package for working with DICOM files, the standard format for medical imaging data. This skill provides guidance on reading, writing, and manipulating DICOM files, including working with pixel data, metadata, and various compression formats.
+
+## When to Use This Skill
+
+Use this skill when working with:
+- Medical imaging files (CT, MRI, X-ray, ultrasound, PET, etc.)
+- DICOM datasets requiring metadata extraction or modification
+- Pixel data extraction and image processing from medical scans
+- DICOM anonymization for research or data sharing
+- Converting DICOM files to standard image formats
+- Compressed DICOM data requiring decompression
+- DICOM sequences and structured reports
+- Multi-slice volume reconstruction
+- PACS (Picture Archiving and Communication System) integration
+
+## Core Workflows
+
+### Reading DICOM Files
+
+Read a DICOM file using `pydicom.dcmread()`:
+
+```python
+import pydicom
+
+# Read a DICOM file
+ds = pydicom.dcmread('path/to/file.dcm')
+
+# Access metadata
+print(f"Patient Name: {ds.PatientName}")
+print(f"Study Date: {ds.StudyDate}")
+print(f"Modality: {ds.Modality}")
+
+# Display all elements
+print(ds)
+```
+
+**Key points:**
+- `dcmread()` returns a `Dataset` object
+- Access data elements using attribute notation (e.g., `ds.PatientName`) or tag notation (e.g., `ds[0x0010, 0x0010]`)
+- Use `ds.file_meta` to access file metadata like Transfer Syntax UID
+- Handle missing attributes with `getattr(ds, 'AttributeName', default_value)` or `hasattr(ds, 'AttributeName')`
+
+### Working with Pixel Data
+
+Extract and manipulate image data from DICOM files:
+
+```python
+import pydicom
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Read DICOM file
+ds = pydicom.dcmread('image.dcm')
+
+# Get pixel array (requires numpy)
+pixel_array = ds.pixel_array
+
+# Apply windowing for display (CT/MRI)
+if hasattr(ds, 'WindowCenter') and hasattr(ds, 'WindowWidth'):
+    from pydicom.pixel_data_handlers.util import apply_voi_lut
+    windowed_image = apply_voi_lut(pixel_array, ds)
+else:
+    windowed_image = pixel_array
+
+# Display image
+plt.imshow(windowed_image, cmap='gray')
+plt.title(f"{ds.Modality} - {ds.StudyDescription}")
+plt.axis('off')
+plt.show()
+```
+
+**Working with color images:**
+
+```python
+# RGB images have shape (rows, columns, 3)
+if ds.PhotometricInterpretation == 'RGB':
+    rgb_image = ds.pixel_array
+    plt.imshow(rgb_image)
+elif ds.PhotometricInterpretation == 'YBR_FULL':
+    from pydicom.pixel_data_handlers.util import convert_color_space
+    rgb_image = convert_color_space(ds.pixel_array, 'YBR_FULL', 'RGB')
+    plt.imshow(rgb_image)
+```
+
+**Multi-frame images (videos/series):**
+
+```python
+# For multi-frame DICOM files
+if hasattr(ds, 'NumberOfFrames') and ds.NumberOfFrames > 1:
+    frames = ds.pixel_array  # Shape: (num_frames, rows, columns)
+    print(f"Number of frames: {frames.shape[0]}")
+
+    # Display specific frame
+    plt.imshow(frames[0], cmap='gray')
+```
+
+# Normalize to 0-255 range
+if pixel_array.dtype != np.uint8:
+    pixel_array = ((pixel_array - pixel_array.min()) /
+                   (pixel_array.max() - pixel_array.min()) * 255).astype(np.uint8)
+
+# Save as PNG
+image = Image.fromarray(pixel_array)
+image.save('output.png')
+
+

package/skills/pyhealth/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: pyhealth
+description: Build clinical/healthcare deep-learning pipelines with PyHealth — loading EHR/signal/imaging datasets (MIMIC-III/IV, eICU, OMOP, SleepEDF, ChestXray14, EHRShot), defining tasks (mortality, readmission, length-of-stay, drug recommendation, sleep staging, ICD coding, EEG events), instantiating models (Transformer, RETAIN, GAMENet, SafeDrug, MICRON, StageNet, AdaCare, CNN/RNN/MLP), training with the PyHealth Trainer, computing clinical metrics, and using medical code utilities (ICD/ATC/NDC/RxNorm lookup and cross-mapping). Use this skill whenever the user mentions PyHealth, MIMIC, eICU, OMOP, EHR modeling, clinical prediction, drug recommendation, sleep staging, medical code mapping, ICD/ATC codes, or any healthcare ML pipeline that fits the dataset → task → model → trainer → metrics pattern, even if "PyHealth" isn't named explicitly.
+---
+
+# PyHealth
+
+PyHealth (https://pyhealth.dev/) is a Python toolkit for clinical deep learning. It provides a unified, modular pipeline across electronic health records (EHR), physiological signals, and medical imaging.
+
+The library is built around a **5-stage pipeline** — `Dataset → Task → Model → Trainer → Metrics` — where each stage is replaceable and the interfaces between stages are stable. Code that follows this pipeline shape composes well; code that bypasses it usually fights the library.
+
+## When to use this skill
+
+Use this skill whenever the user is doing clinical/healthcare ML and any of the following are true:
+
+- They mention PyHealth, MIMIC-III/IV, eICU, OMOP-CDM, EHRShot, SleepEDF, SHHS, ISRUC, COVID19-CXR, ChestX-ray14, TUEV/TUAB.
+- They want to predict mortality, readmission, length of stay, drug recommendations, sleep stages, ICD codes, EEG events, or de-identification.
+- They need to look up or cross-map medical codes (ICD-9-CM, ICD-10-CM, ATC, NDC, RxNorm, CCS).
+- They have EHR-shaped data and want to train a clinical model without writing the plumbing themselves.
+
+PyHealth is the right tool when the workflow fits its 5 stages. If the user just wants generic PyTorch on tabular data, this skill is not necessary.
+
+# Create a project with the right Python
+uv init my-pyhealth-project
+cd my-pyhealth-project
+uv python pin 3.12
+
+# Add PyHealth (this also pulls in PyTorch and friends)
+uv add pyhealth
+
+# Run scripts inside the env
+uv run python train.py
+```
+
+For a one-off script without a project, use `uv run --with pyhealth python script.py`. For the legacy 1.x line (Python 3.9+), `uv add pyhealth==1.16`. Detailed install notes, MIMIC access, and GPU/CPU device tips are in `(see docs)`.
+
+## The 5-stage pipeline
+
+A complete pipeline is typically <20 lines. This is the canonical shape — start here and modify pieces:
+
+```python
+from pyhealth.datasets import MIMIC3Dataset, split_by_patient, get_dataloader
+from pyhealth.tasks import MortalityPredictionMIMIC3
+from pyhealth.models import Transformer
+from pyhealth.trainer import Trainer
+from pyhealth.metrics.binary import binary_metrics_fn
+
+# 1. Dataset — raw patient registry
+base = MIMIC3Dataset(
+    root="https://storage.googleapis.com/pyhealth/Synthetic_MIMIC-III/",
+    tables=["DIAGNOSES_ICD", "PROCEDURES_ICD", "PRESCRIPTIONS"],
+)
+
+# 2. Task — converts patients into supervised samples
+samples = base.set_task(MortalityPredictionMIMIC3())
+
+# 3. Split + DataLoaders (split by patient to avoid leakage)
+train_ds, val_ds, test_ds = split_by_patient(samples, [0.8, 0.1, 0.1])
+train_loader = get_dataloader(train_ds, batch_size=32, shuffle=True)
+val_loader   = get_dataloader(val_ds,   batch_size=32, shuffle=False)
+test_loader  = get_dataloader(test_ds,  batch_size=32, shuffle=False)
+
+# 4. Model — must be passed the SampleDataset, not the BaseDataset
+model = Transformer(dataset=samples)
+
+# 5. Train + evaluate
+trainer = Trainer(model=model)
+trainer.train(
+    train_dataloader=train_loader,
+    val_dataloader=val_loader,
+    epochs=50,
+    monitor="pr_auc",
+)
+
+y_true, y_prob, _ = trainer.inference(test_loader)
+print(binary_metrics_fn(y_true, y_prob, metrics=["pr_auc", "roc_auc"]))
+```
+
+A copy-pasteable starter is in `assets/starter_pipeline.py`.
+
+## Critical things to get right
+
+These are the mistakes that PyHealth code most commonly trips on. Internalize them before writing pipelines:
+
+1. **Models take a `SampleDataset`, not a `BaseDataset`.** `MIMIC3Dataset(...)` returns a `BaseDataset` (a queryable patient registry). Only after `.set_task(task)` do you get a `SampleDataset`, which is what models, splitters, and DataLoaders expect. If you pass `base` to a model, it will fail or behave wrong.
+
+2. **Always split by patient (or visit), not by sample.** Random sample-level splits leak information across train/test because the same patient can appear in both. Use `split_by_patient` for patient-level prediction, `split_by_visit` only when visits are independent.
+
+3. **Match the task to the dataset.** Tasks are dataset-specific: `MortalityPredictionMIMIC3` won't work on MIMIC-IV — use `MortalityPredictionMIMIC4` or `InHospitalMortalityMIMIC4`. The full mapping is in `(see docs)`.
+
+4. **Pick `monitor` to match the task type.** For binary classification use `"pr_auc"` or `"roc_auc"`. For multilabel (drug rec) use `"pr_auc_samples"` or `"jaccard_samples"`. For multiclass use `"accuracy"` or `"f1_macro"`. Wrong monitor → checkpoint selection saves the wrong epoch.
+
+5. **MIMIC-IV uses `ehr_root=`, not `root=`.** This is the one inconsistency in the dataset constructors.
+
+6. **For reproducible work, point `cache_dir=` somewhere persistent.** PyHealth caches the parsed dataset; without `cache_dir`, you re-parse every run.
+
+## How to use this skill
+
+PyHealth has a large API surface — there's no point loading it all at once. Read the reference file that matches the user's task:
+
+| If the user is asking about… | Read |
+|---|---|
+| Installing, env setup, MIMIC access, GPU | `(see docs)` |
+| Which dataset class to use, loading patterns, splitting | `(see docs)` |
+| What prediction task to choose (mortality, readmission, drug rec, sleep…) | `(see docs)` |
+| Picking a model architecture, model-specific arguments | `(see docs)` |
+| Looking up or cross-mapping ICD/ATC/NDC/RxNorm/CCS codes, tokenizers | `(see docs)` |
+| End-to-end recipes for common scenarios | `(see docs)` |
+
+For multi-step tasks (e.g., "build a drug recommendation pipeline on MIMIC-IV"), read `tasks.md` + `models.md` + `examples.md` together — they cross-reference each other.
+
+## A note on style
+
+Write minimal, idiomatic PyHealth. The library is opinionated; lean into its abstractions instead of reimplementing them in raw PyTorch. If you find yourself writing a custom training loop, ask whether `Trainer` would do the job — it almost always will, and it handles checkpointing, logging, and best-model selection for free.
+
+When the user has private MIMIC access, point them at the local CSV root; for demos and learning, the synthetic MIMIC-III bucket (`https://storage.googleapis.com/pyhealth/Synthetic_MIMIC-III/`) is fine and works without credentialing.
+```

package/skills/pylabrobot/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: pylabrobot
+description: Vendor-agnostic lab automation framework. Use when controlling multiple equipment types (Hamilton, Tecan, Opentrons, plate readers, pumps) or needing unified programming across different vendors. Best for complex workflows, multi-vendor setups, simulation. For Opentrons-only protocols with official API, opentrons-integration may be simpler.
+---
+
+# PyLabRobot
+
+## Overview
+
+PyLabRobot is a hardware-agnostic, pure Python Software Development Kit for automated and autonomous laboratories. Use this skill to control liquid handling robots, plate readers, pumps, heater shakers, incubators, centrifuges, and other laboratory automation equipment through a unified Python interface that works across platforms (Windows, macOS, Linux).
+
+## When to Use This Skill
+
+Use this skill when:
+- Programming liquid handling robots (Hamilton STAR/STARlet, Opentrons OT-2, Tecan EVO)
+- Automating laboratory workflows involving pipetting, sample preparation, or analytical measurements
+- Managing deck layouts and laboratory resources (plates, tips, containers, troughs)
+- Integrating multiple lab devices (liquid handlers, plate readers, heater shakers, pumps)
+- Creating reproducible laboratory protocols with state management
+- Simulating protocols before running on physical hardware
+- Reading plates using BMG CLARIOstar or other supported plate readers
+- Controlling temperature, shaking, centrifugation, or other material handling operations
+- Working with laboratory automation in Python
+
+## Core Capabilities
+
+PyLabRobot provides comprehensive laboratory automation through six main capability areas, each detailed in the references/ directory:
+
+### 1. Liquid Handling (`(see docs)`)
+
+Control liquid handling robots for aspirating, dispensing, and transferring liquids. Key operations include:
+- **Basic Operations**: Aspirate, dispense, transfer liquids between wells
+- **Tip Management**: Pick up, drop, and track pipette tips automatically
+- **Advanced Techniques**: Multi-channel pipetting, serial dilutions, plate replication
+- **Volume Tracking**: Automatic tracking of liquid volumes in wells
+- **Hardware Support**: Hamilton STAR/STARlet, Opentrons OT-2, Tecan EVO, and others
+
+### 2. Resource Management (`(see docs)`)
+
+Manage laboratory resources in a hierarchical system:
+- **Resource Types**: Plates, tip racks, troughs, tubes, carriers, and custom labware
+- **Deck Layout**: Assign resources to deck positions with coordinate systems
+- **State Management**: Track tip presence, liquid volumes, and resource states
+- **Serialization**: Save and load deck layouts and states from JSON files
+- **Resource Discovery**: Access wells, tips, and containers through intuitive APIs
+
+### 3. Hardware Backends (`(see docs)`)
+
+Connect to diverse laboratory equipment through backend abstraction:
+- **Liquid Handlers**: Hamilton STAR (full support), Opentrons OT-2, Tecan EVO
+- **Simulation**: ChatterboxBackend for protocol testing without hardware
+- **Platform Support**: Works on Windows, macOS, Linux, and Raspberry Pi
+- **Backend Switching**: Change robots by swapping backend without rewriting protocols
+
+### 4. Analytical Equipment (`(see docs)`)
+
+Integrate plate readers and analytical instruments:
+- **Plate Readers**: BMG CLARIOstar for absorbance, luminescence, fluorescence
+- **Scales**: Mettler Toledo integration for mass measurements
+- **Integration Patterns**: Combine liquid handlers with analytical equipment
+- **Automated Workflows**: Move plates between devices automatically
+
+### 5. Material Handling (`(see docs)`)
+
+Control environmental and material handling equipment:
+- **Heater Shakers**: Hamilton HeaterShaker, Inheco ThermoShake
+- **Incubators**: Inheco and Thermo Fisher incubators with temperature control
+- **Centrifuges**: Agilent VSpin with bucket positioning and spin control
+- **Pumps**: Cole Parmer Masterflex for fluid pumping operations
+- **Temperature Control**: Set and monitor temperatures during protocols
+
+### 6. Visualization & Simulation (`(see docs)`)
+
+Visualize and simulate laboratory protocols:
+- **Browser Visualizer**: Real-time 3D visualization of deck state
+- **Simulation Mode**: Test protocols without physical hardware
+- **State Tracking**: Monitor tip presence and liquid volumes visually
+- **Deck Editor**: Graphical tool for designing deck layouts
+- **Protocol Validation**: Verify protocols before running on hardware
+
+## Quick Start
+
+To get started with PyLabRobot, install the package and initialize a liquid handler:
+
+```python
+# Basic liquid handling setup
+from pylabrobot.liquid_handling import LiquidHandler
+from pylabrobot.liquid_handling.backends import STAR
+from pylabrobot.resources import STARLetDeck
+
+# Initialize liquid handler
+lh = LiquidHandler(backend=STAR(), deck=STARLetDeck())
+await lh.setup()
+
+# Basic operations
+await lh.pick_up_tips(tip_rack["A1:H1"])
+await lh.aspirate(plate["A1"], vols=100)
+await lh.dispense(plate["A2"], vols=100)
+await lh.drop_tips()
+```

package/skills/pymatgen/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: pymatgen
+description: Materials science computational library. Use when working with crystal structures, phase diagrams, electronic structure, diffusion analysis, or materials property prediction. Trigger on imports of pymatgen, Structure, PhaseDiagram, or mentions of crystal lattice, band structure, DFT, materials genome.
+---
+# pymatgen
+
+Use this skill for materials science computations.
+
+## Core patterns
+
+- **Structure**: `Structure.from_file('POSCAR')` / `structure.to('cif')`.
+- **Lattice**: `Lattice.cubic(4.2)`, `Lattice.hexagonal(a=3.0, c=5.0)`.
+- **Sites**: `structure.sites` → `site.species`, `site.coords`, `site.frac_coords`.
+- **Phase diagram**: `PhaseDiagram(entries)` → `pd.get_equilibrium_reaction_energy(entry)`.
+- **Diffusion**: `DiffusionAnalyzer.from_files()` for MD trajectory analysis.
+
+## Rules
+
+- Always check structure validity: `structure.is_valid(tol=0.5)`.
+- Use `structure.make_supercell()` for defect calculations, not manual replication.
+- For DFT workflows, validate k-points and convergence parameters.
+
+## Anti-patterns
+
+- Don't compare floating point coordinates directly — use `structure.matches(other)`.
+- Don't create structures with overlapping sites without checking tolerance.
+
+

package/skills/pymc/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: pymc
+description: Bayesian modeling with PyMC. Build hierarchical models, MCMC (NUTS), variational inference, LOO/WAIC comparison, posterior checks, for probabilistic programming and inference.
+---
+
+# PyMC Bayesian Modeling
+
+## Overview
+
+PyMC is a Python library for Bayesian modeling and probabilistic programming. Build, fit, validate, and compare Bayesian models using PyMC's modern API (version 5.x+), including hierarchical models, MCMC sampling (NUTS), variational inference, and model comparison (LOO, WAIC).
+
+## When to Use This Skill
+
+This skill should be used when:
+- Building Bayesian models (linear/logistic regression, hierarchical models, time series, etc.)
+- Performing MCMC sampling or variational inference
+- Conducting prior/posterior predictive checks
+- Diagnosing sampling issues (divergences, convergence, ESS)
+- Comparing multiple models using information criteria (LOO, WAIC)
+- Implementing uncertainty quantification through Bayesian methods
+- Working with hierarchical/multilevel data structures
+- Handling missing data or measurement error in a principled way
+
+## Standard Bayesian Workflow
+
+Follow this workflow for building and validating Bayesian models:
+
+### 1. Data Preparation
+
+```python
+import pymc as pm
+import arviz as az
+import numpy as np
+
+# Load and prepare data
+X = ...  # Predictors
+y = ...  # Outcomes
+
+# Standardize predictors for better sampling
+X_mean = X.mean(axis=0)
+X_std = X.std(axis=0)
+X_scaled = (X - X_mean) / X_std
+```
+
+**Key practices:**
+- Standardize continuous predictors (improves sampling efficiency)
+- Center outcomes when possible
+- Handle missing data explicitly (treat as parameters)
+- Use named dimensions with `coords` for clarity
+
+### 2. Model Building
+
+```python
+coords = {
+    'predictors': ['var1', 'var2', 'var3'],
+    'obs_id': np.arange(len(y))
+}
+
+with pm.Model(coords=coords) as model:
+    # Priors
+    alpha = pm.Normal('alpha', mu=0, sigma=1)
+    beta = pm.Normal('beta', mu=0, sigma=1, dims='predictors')
+    sigma = pm.HalfNormal('sigma', sigma=1)
+
+    # Linear predictor
+
+### 3. Prior Predictive Check
+
+**Always validate priors before fitting:**
+
+```python
+with model:
+    prior_pred = pm.sample_prior_predictive(samples=1000, random_seed=42)
+
+# Visualize
+az.plot_ppc(prior_pred, group='prior')
+```
+
+**Check:**
+- Do prior predictions span reasonable values?
+- Are extreme values plausible given domain knowledge?
+- If priors generate implausible data, adjust and re-check
+
+### 4. Fit Model
+
+```python
+with model:
+    # Optional: Quick exploration with ADVI
+    # approx = pm.fit(n=20000)
+
+    # Full MCMC inference
+    idata = pm.sample(
+        draws=2000,
+        tune=1000,
+        chains=4,
+        target_accept=0.9,
+        random_seed=42,
+        idata_kwargs={'log_likelihood': True}  # For model comparison
+
+### 5. Check Diagnostics
+
+**Use the diagnostic script:**
+
+```python
+from scripts.model_diagnostics import check_diagnostics
+
+results = check_diagnostics(idata, var_names=['alpha', 'beta', 'sigma'])
+```