@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/bioinformatics-workflows/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: bioinformatics-workflows
+description: Bioinformatics pipeline work on FASTA, FASTQ, SAM/BAM/CRAM and VCF files with Biopython, samtools, bcftools, seqkit, FastQC, aligners such as bwa-mem2 and minimap2, and Snakemake or Nextflow workflows run in pinned conda, Docker or Apptainer environments so results reproduce. Use when parsing or converting sequence and alignment files, writing or debugging a Snakemake or Nextflow pipeline, running read QC, alignment or variant calling steps, or making a genomics analysis reproducible on a laptop, HPC cluster or cloud.
+license: MIT
+compatibility: Any Agent Skills host. Needs the tools the pipeline uses (for example samtools, bcftools, snakemake or nextflow) and a conda/mamba, Docker or Apptainer install for pinned environments.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "samtools, bcftools"
+  kete-loom/owner: "Kete-org"
+---
+
+# Bioinformatics workflows
+
+Get sequence data from raw reads to results with every step scripted, every tool version pinned, and every intermediate file checked before the next step trusts it.
+
+## Scope and limits
+
+- This skill covers data handling and pipeline engineering. It does not choose the statistical model for a study or interpret variants clinically. Clinical or diagnostic use of variant calls needs a validated pipeline and review by a qualified clinical scientist; say so when the user's data is from patients.
+- Human genomic data is personal data. Never upload it to a public service, paste it into an issue, or commit it to git. Ask where the data is allowed to live before moving it.
+
+## 0. Before you start
+
+1. Ask for, or find in the repo: organism and **reference genome build** (for example GRCh38 vs GRCh37, with the exact FASTA source), sequencing type (short-read Illumina, long-read ONT/PacBio), single or paired-end, and the expected output.
+2. Inspect the inputs before writing code: `seqkit stats reads.fastq.gz`, `samtools quickcheck -v *.bam`, `samtools view -H sample.bam | head`, `bcftools view -h calls.vcf.gz | tail -5`.
+3. Check that contig names agree across the reference, BAM header and VCF (`chr1` vs `1`). Mismatched builds or names are the most common silent failure. Stop and ask if they differ.
+
+## 1. Know the formats
+
+Detail and gotchas in `references/formats.md`. The rules that bite most often:
+
+- FASTQ quality scores are Phred+33 on modern Illumina and ONT; old data may be Phred+64. Paired files must stay in the same read order.
+- SAM text and VCF are 1-based, BED is 0-based half-open, and pysam returns 0-based starts (`read.reference_start`, `record.start`) even for SAM and VCF. Convert explicitly.
+- BAM and VCF need sorting and an index (`.bai`/`.csi`, `.tbi`/`.csi`) before region queries. Compress VCF with `bgzip`, not `gzip`.
+- CRAM needs the exact reference FASTA it was written against to decode.
+
+## 2. Pick the tool
+
+| Job | Use |
+|---|---|
+| Inspect, filter, sort, index BAM/CRAM | `samtools view`, `sort`, `index`, `flagstat`, `idxstats` |
+| Filter, normalise, merge, query VCF/BCF | `bcftools view`, `norm`, `merge`, `query`, `index` |
+| Fast FASTA/FASTQ stats, subset, convert | `seqkit` |
+| Read QC and reports | FastQC, then MultiQC to aggregate |
+| Short-read alignment to a genome | `bwa-mem2` (or `bwa mem`), `bowtie2` |
+| Long reads, assemblies, spliced long reads | `minimap2` with the right preset (`-ax map-ont`, `-ax map-hifi`, `-ax splice`) |
+| Interval arithmetic | `bedtools` |
+| Parsing in Python | Biopython `SeqIO` for sequences, `pysam` for BAM/VCF |
+
+Command patterns are in `references/commands.md`. Prefer a maintained community tool over hand-written parsing. Never parse BAM or VCF with regex.
+
+## 3. Biopython essentials
+
+- `SeqIO.parse(path, "fasta")` and `SeqIO.parse(handle, "fastq")` stream records; use them in a loop, not `list(...)`, for large files. Open `.gz` with `gzip.open(path, "rt")`.
+- `SeqIO.index(path, "fasta")` for random access by ID without loading the file.
+- `Bio.Entrez` needs `Entrez.email` set; keep within NCBI limits (3 requests/second, 10 with an API key).
+- Write with `SeqIO.write(records, out, "fasta")`. Check record IDs are unique.
+
+## 4. Build the pipeline in a workflow manager
+
+Use Snakemake or Nextflow for anything with more than two steps or more than a handful of samples. Templates are in `references/workflow-managers.md`.
+
+1. One rule or process per tool invocation. Inputs and outputs declared, never implied.
+2. Sample list comes from a config or sample sheet (`config.yaml`, `samplesheet.csv`), never hard-coded.
+3. Each rule or process names its own environment: a conda YAML with pinned versions, or a container image with a tag (better, a digest).
+4. Threads and memory declared per step, so the executor can schedule on a cluster.
+5. Write logs per step and per sample.
+6. Dry-run before the real run: `snakemake -n` or `nextflow run main.nf -preview` (or `-stub-run` with stub blocks).
+7. Rerun only what changed: Snakemake does this by default; Nextflow needs `-resume`.
+8. Before writing a pipeline from scratch, check whether an nf-core pipeline or a Snakemake workflow catalog entry already does the job; reuse it if it fits.
+
+## 5. Make it reproducible
+
+- Pin every tool version (`samtools=1.24`, not `samtools`). Export the solved environment (`conda env export --no-builds` or a lock file) and commit it.
+- Record the reference genome source URL, build and checksum. Keep reference files out of git; document how to fetch them.
+- Fix random seeds where tools take one (subsampling: `seqkit sample -s 11`, `samtools view -s 42.1`).
+- Generate a run report: Snakemake `--report report.html`, Nextflow `-with-report -with-trace -with-timeline`.
+- Store raw data read-only. Never overwrite inputs in place.
+
+## 6. Verify each step
+
+After each stage, check before moving on:
+
+- QC: FastQC/MultiQC flags reviewed; adapter content and per-base quality noted.
+- Alignment: `samtools flagstat` mapping rate and properly-paired rate in a sensible range for the data type; `samtools quickcheck` passes.
+- Variants: `bcftools stats` counts, transition/transversion ratio plausible for the organism and region; `bcftools norm -f ref.fa -c w -Ou -o /dev/null calls.vcf.gz` warns about no REF mismatches against the reference.
+- Row and record counts agree between input and output where they should.
+
+If a number is far outside what the data type normally gives, stop and report it to the user before continuing.
+
+## Never
+
+- Mix reference builds in one analysis.
+- Use `latest` container tags or unpinned conda packages in a pipeline others will run.
+- Delete intermediate files the user has not agreed can go (use Snakemake `temp()` or Nextflow cleanup only when agreed).
+- Commit raw sequencing data, reference genomes or credentials to git.
+
+## Report back
+
+```
+Inputs: <files, organism, build, read type>
+Pipeline: <Snakemake|Nextflow>, entry <file>, environments <how pinned>
+Ran: <exact command>, <dry-run result>, <real run result>
+Checks: <QC, flagstat, bcftools stats numbers>
+Outputs: <paths>
+Open issues: <anything outside expected ranges, unresolved mismatches>
+```

package/skills/bioinformatics-workflows/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My bcftools merge fails because the contig names in one VCF are chr1 and the other is 1, how do I fix it safely?",
+    "Write a Snakemake pipeline that runs FastQC, aligns paired-end reads with bwa-mem2 and outputs sorted indexed BAMs",
+    "Parse this FASTQ file with Biopython and drop reads shorter than 50 bases",
+    "Our Nextflow run on the cluster died halfway, how do I restart it without redoing the alignment tasks?",
+    "Pin the conda environments for our variant calling workflow so the lab next door gets the same samtools version"
+  ],
+  "should_not_trigger": [
+    "Find and summarise recent papers on CRISPR off-target prediction methods",
+    "Set up an Airflow DAG that loads our sales CSVs into the warehouse every night",
+    "Tidy my exploratory pandas notebook and move the cleaning code into a module",
+    "Write a dbt model that joins orders to customers",
+    "Write a GitHub Actions workflow that runs pytest on every pull request"
+  ]
+}

package/skills/bioinformatics-workflows/references/commands.md

@@ -0,0 +1,71 @@
+# Command patterns
+
+Check each tool's `--help` for the installed version before relying on a flag.
+
+## Inspect
+
+```bash
+seqkit stats -a reads_R1.fastq.gz reads_R2.fastq.gz
+samtools quickcheck -v sample.bam && echo ok
+samtools view -H sample.bam            # header: @SQ contigs, @RG read groups, @PG programs
+samtools flagstat -@ 4 sample.bam
+samtools idxstats sample.bam           # reads per contig (needs index)
+bcftools view -h calls.vcf.gz | tail
+bcftools stats calls.vcf.gz > calls.stats.txt
+```
+
+## QC
+
+```bash
+mkdir -p qc
+fastqc -t 4 -o qc/ reads_R1.fastq.gz reads_R2.fastq.gz
+multiqc qc/ -o qc/
+```
+
+## Align short reads and make an indexed BAM
+
+```bash
+bwa-mem2 index ref.fa                                   # once per reference
+bwa-mem2 mem -t 8 -R '@RG\tID:s1\tSM:s1\tPL:ILLUMINA' ref.fa R1.fq.gz R2.fq.gz \
+  | samtools sort -@ 4 -o s1.sorted.bam -
+samtools index s1.sorted.bam
+```
+
+Long reads: `minimap2 -ax map-ont ref.fa reads.fq.gz | samtools sort -o out.bam -` (use `map-hifi` for PacBio HiFi, `splice` for spliced cDNA).
+
+## Mark duplicates with samtools
+
+```bash
+samtools sort -n -o s1.name.bam s1.sorted.bam
+samtools fixmate -m s1.name.bam s1.fixmate.bam
+samtools sort -o s1.pos.bam s1.fixmate.bam
+samtools markdup s1.pos.bam s1.markdup.bam
+samtools index s1.markdup.bam
+```
+
+## Variants
+
+```bash
+bcftools mpileup -f ref.fa -Ou s1.markdup.bam | bcftools call -mv -Oz -o s1.vcf.gz
+bcftools index -t s1.vcf.gz
+bcftools norm -f ref.fa -m -any -Oz -o s1.norm.vcf.gz s1.vcf.gz
+bcftools view -i 'QUAL>=30 && INFO/DP>=10' -Oz -o s1.filt.vcf.gz s1.norm.vcf.gz
+bcftools query -f '%CHROM\t%POS\t%REF\t%ALT\t[%GT]\n' s1.filt.vcf.gz
+```
+
+Filter thresholds are examples; choose them for the data and caller, and say which you used.
+
+## Regions and intervals
+
+```bash
+samtools view -b -o region.bam s1.markdup.bam chr1:1000000-2000000
+bcftools view -r chr1:1000000-2000000 s1.filt.vcf.gz
+bedtools intersect -a calls.bed -b targets.bed -u
+```
+
+## Subsampling with a fixed seed
+
+```bash
+seqkit sample -s 11 -p 0.1 reads.fq.gz -o sub.fq.gz
+samtools view -b -s 42.1 -o sub.bam s1.markdup.bam     # seed 42, keep 10%
+```

package/skills/bioinformatics-workflows/references/formats.md

@@ -0,0 +1,24 @@
+# Sequence and alignment formats
+
+| Format | What it holds | Coordinates | Compression and index |
+|---|---|---|---|
+| FASTA | sequences with `>id description` headers | n/a | `bgzip` + `samtools faidx` (`.fai`, plus `.gzi` when bgzipped) |
+| FASTQ | reads: 4 lines per record (`@id`, sequence, `+`, qualities) | n/a | gzip or bgzip; no index needed for streaming |
+| SAM | text alignments, header lines start with `@` | 1-based `POS` | n/a |
+| BAM | binary SAM | as SAM | BGZF; coordinate-sort then `samtools index` (`.bai`, or `.csi` for very long contigs) |
+| CRAM | reference-compressed alignments | as SAM | needs the same reference FASTA to decode; `.crai` index |
+| VCF / BCF | variant calls per site, genotypes per sample | 1-based `POS` | `bgzip` + `bcftools index -t` (`.tbi`) or `-c` (`.csi`) |
+| BED | intervals | 0-based start, end exclusive | `bgzip` + `tabix -p bed` |
+| GFF3 / GTF | gene annotations | 1-based, inclusive | `bgzip` + `tabix -p gff` after sorting |
+
+## Gotchas
+
+- **Quality encoding.** Phred+33 is standard (Illumina 1.8+ and later, ONT, PacBio). If any quality character is below `;` (ASCII 59), the file must be Phred+33, because Phred+64 and Solexa never use those characters; FastQC's Basic Statistics module reports the encoding it used.
+- **Paired-end order.** R1 and R2 must list the same reads in the same order. Tools that filter one file must filter both together (for example `fastp -i R1 -I R2 -o ... -O ...`).
+- **Read names.** Some tools strip `/1` `/2` suffixes or comments after whitespace; keep names consistent across files.
+- **SAM flags.** Decode with `samtools flags <n>`. Common: 4 unmapped, 256 secondary, 1024 duplicate, 2048 supplementary. Filtering primary mapped reads: `samtools view -F 0x904`.
+- **pysam coordinates.** pysam is 0-based half-open (`reference_start`, `VariantRecord.start`); `VariantRecord.pos` is the 1-based VCF POS. Mixing them gives off-by-one errors.
+- **Sorting.** Coordinate sort for indexing and variant calling; name sort (`samtools sort -n`) for tools that need mates adjacent, such as `samtools fixmate`.
+- **VCF normalisation.** Left-align and split multi-allelic sites before comparing call sets: `bcftools norm -f ref.fa -m -any`.
+- **Contig names.** `chr1` (UCSC style) vs `1` (Ensembl/NCBI style). Check with `samtools view -H` and `bcftools view -h`; rename with `bcftools annotate --rename-chrs` only after confirming the builds match.
+- **bgzip vs gzip.** Indexed formats need BGZF blocks; plain `gzip` output cannot be indexed.

package/skills/bioinformatics-workflows/references/workflow-managers.md

@@ -0,0 +1,107 @@
+# Workflow managers
+
+## Snakemake
+
+`Snakefile`:
+
+```python
+configfile: "config.yaml"
+SAMPLES = config["samples"]
+
+rule all:
+    input: expand("results/{s}.flagstat.txt", s=SAMPLES)
+
+rule align:
+    input:
+        r1="data/{s}_R1.fastq.gz",
+        r2="data/{s}_R2.fastq.gz",
+        ref=config["reference"],
+    output: "results/{s}.sorted.bam"
+    log: "logs/align/{s}.log"
+    threads: 8
+    resources: mem_mb=16000
+    conda: "envs/align.yaml"
+    shell:
+        "(bwa-mem2 mem -t {threads} {input.ref} {input.r1} {input.r2} "
+        "| samtools sort -@ {threads} -o {output} -) 2> {log}"
+
+rule flagstat:
+    input: "results/{s}.sorted.bam"
+    output: "results/{s}.flagstat.txt"
+    conda: "envs/align.yaml"
+    shell: "samtools flagstat {input} > {output}"
+```
+
+`envs/align.yaml` pins versions:
+
+```yaml
+channels: [conda-forge, bioconda]   # bioconda's recommended order; set channel_priority strict in .condarc
+dependencies:
+  - bwa-mem2=2.3       # example pins: current bioconda releases in Oct 2026; pin what you tested
+  - samtools=1.24
+```
+
+Run:
+
+```bash
+snakemake -n                                   # dry run: shows the job plan
+snakemake --cores 8 --software-deployment-method conda   # short form: --sdm conda; older: --use-conda
+snakemake --cores 8 --sdm apptainer            # rules with a container: directive
+snakemake --report report.html                 # after a run
+snakemake --lint                               # style and best-practice checks
+```
+
+Use `temp()` for intermediates that may be deleted and `protected()` for outputs that must not be overwritten. Cluster and cloud execution uses executor plugins (`--executor slurm` with the slurm plugin installed); configure them in a profile rather than on the command line.
+
+## Nextflow (DSL2)
+
+`main.nf`:
+
+```groovy
+params.samplesheet = 'samplesheet.csv'
+params.reference   = 'ref/genome.fa'
+
+process ALIGN {
+    tag "$sample"
+    cpus 8
+    memory '16 GB'
+    container 'quay.io/biocontainers/<image>:<tag>'   // pin a tag or digest
+    input:
+    tuple val(sample), path(r1), path(r2)
+    path ref
+    output:
+    tuple val(sample), path("${sample}.sorted.bam")
+    script:
+    """
+    bwa-mem2 mem -t ${task.cpus} ${ref} ${r1} ${r2} | samtools sort -@ ${task.cpus} -o ${sample}.sorted.bam -
+    """
+}
+
+workflow {
+    reads = Channel.fromPath(params.samplesheet)
+        .splitCsv(header: true)
+        .map { row -> tuple(row.sample, file(row.r1), file(row.r2)) }
+    ALIGN(reads, file(params.reference))
+}
+```
+
+Note: `bwa-mem2` also needs its index files beside the reference; stage them as an extra `path` input or point to the index directory.
+
+Run:
+
+```bash
+nextflow run main.nf -profile docker -preview          # check the workflow compiles without running tasks
+nextflow run main.nf -profile docker -params-file params.yaml
+nextflow run main.nf -profile docker -resume           # reuse cached tasks
+nextflow run main.nf -with-report -with-trace -with-timeline
+nextflow run nf-core/<pipeline> -r <version> -profile docker,test   # pin community pipelines with -r
+nextflow lint main.nf                                   # Nextflow 25.04+
+```
+
+Profiles (`docker`, `apptainer`, `conda`, a cluster executor) live in `nextflow.config`. Always pin nf-core pipelines with `-r <release>`.
+
+## Choosing
+
+- Snakemake: Python-centric team, file-based rules, simple local or Slurm runs.
+- Nextflow: channel-based dataflow, strong container and cloud support, nf-core ecosystem.
+- Either way: one environment per step, config-driven samples, dry run first.

package/skills/blender-automation/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: blender-automation
+description: Scripts Blender through its bpy Python API and command line - inspecting armatures, bone hierarchies, rest and pose transforms, constraints and vertex groups, diagnosing broken rigs and retargeted animation (wrong bone roll, scale on the armature, mismatched rest poses, missing action slots), editing actions and F-Curves through layers, strips and channelbags, batch-editing objects, materials and modifiers across many .blend files, and rendering headless with blender -b. Use when a rig or imported FBX animation looks wrong in Blender, when the same change must be applied to dozens of scenes or assets, or when renders must run from a script or on a farm without the UI.
+license: MIT
+compatibility: Any Agent Skills host. Needs a local Blender install on PATH (examples target Blender 4.4 and later, where actions use slots; 5.0 removed Action.fcurves). GPU rendering needs a supported GPU and driver.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "blender"
+  kete-loom/owner: "Kete-org"
+---
+
+# Blender automation
+
+Drive Blender from scripts so every change is repeatable, reviewable and can run without the UI. Inspect first, change on a copy, verify by reading the data back and rendering a check frame.
+
+## 0. Before you run anything
+
+1. Find the Blender version: `blender --version`. The Python API changes between releases; open the API docs for that exact version (`https://docs.blender.org/api/<major.minor>/`).
+2. Ask the user which `.blend` files are in scope and where outputs should go. **Work on copies**: never save over the user's originals unless they say so.
+3. Run scripts headless with an exit code on failure:
+
+   ```bash
+   blender -b --factory-startup scene.blend --python-exit-code 1 -P script.py -- --out /abs/out
+   ```
+
+   Arguments run in order: load the `.blend` first, then `-o` / `-F`, then `-f` or `-a`. Everything after `--` reaches the script via `sys.argv`. `--factory-startup` skips the user's startup file and add-ons, so enable add-ons the script needs explicitly.
+
+## 1. Inspect before changing
+
+Dump the facts into a text or JSON report rather than guessing from screenshots. Snippets in `references/bpy-inspection.md`:
+
+- Scene: objects, types, parents, collections, frame range, fps, render engine, output settings.
+- Armature: bones with parent, head, tail, roll, `use_deform`, `use_connect`, inherit scale mode; pose bones with rotation mode and constraints.
+- Mesh binding: Armature modifier target, vertex groups that have no matching deform bone, and deform bones with no vertex group.
+- Animation: each object's `animation_data.action`, `action_slot`, NLA tracks, and per-bone F-Curve key counts and frame range.
+- Object transforms: any non-applied scale or rotation on the armature or mesh object.
+
+## 2. Diagnose rigs and animation
+
+Work through `references/rig-and-retarget-checks.md`. The most common causes, in order:
+
+1. **Object scale or rotation not applied** on the armature (typical with FBX at 0.01 scale or a 90 degree X rotation). Animation then moves in the wrong units or axis.
+2. **Rest pose mismatch** between source and target (A-pose versus T-pose), so retargeted rotations are offset everywhere.
+3. **Bone roll differs** between rigs, so local rotation axes do not match and limbs twist.
+4. **Name mismatch**: F-Curve data paths like `pose.bones["mixamorig:LeftArm"].rotation_quaternion` do not match the target bone names, so channels silently do nothing.
+5. **Rotation mode mismatch**: curves on `rotation_euler` while the bone uses quaternions, or the reverse.
+6. **Action not assigned to a slot** (Blender 4.4+): the action is set but `animation_data.action_slot` is empty or targets a different ID, so nothing plays.
+7. **Constraints or IK** overriding the keyed pose, or bones with `inherit_scale` causing creeping scale.
+
+For each issue found, record: symptom, evidence (values read from the file), cause, fix. **Stop and show the user the diagnosis before changing a rig** that other files link to or that is shared by a team.
+
+## 3. Fix
+
+- Apply transforms with `bpy.ops.object.transform_apply` only on a copy, in Object mode with the object active and selected, and check the effect on its children and animation (applying scale to an animated armature changes what the location keys mean).
+- Rename bones or remap F-Curve data paths with a mapping table the user confirms; never guess a mapping for ambiguous bones (fingers, twist bones).
+- To retarget, prefer constraints (Copy Rotation in local space, or a dedicated retargeting add-on the user already uses) and bake to a new action (`bpy.ops.nla.bake` with `visual_keying=True`, `clear_constraints=True`), keeping the original action.
+- Edit keys through the layered action API (`references/bpy-inspection.md`, "Actions and F-Curves"). In Blender 5.0 and later, `Action.fcurves` no longer exists.
+
+## 4. Batch edits
+
+Pattern in `references/batch-and-render.md`:
+
+1. List the target files and print the plan (file, what will change) before changing anything.
+2. Open each file in a fresh Blender process (one `blender -b file.blend -P edit.py` per file) so state does not leak between files.
+3. Make the change through data (`bpy.data`), not operators, wherever possible; operators depend on context and selection.
+4. Save to an output folder with `bpy.ops.wm.save_as_mainfile(filepath=..., copy=True)`.
+5. Re-open each output and assert the change took effect; write a per-file result line (ok, skipped, failed with reason).
+
+## 5. Headless rendering
+
+```bash
+# one frame
+blender -b shot.blend -E CYCLES -o /abs/renders/shot_#### -F PNG -f 1
+# a range
+blender -b shot.blend -o /abs/renders/shot_#### -F OPEN_EXR -s 1 -e 240 -a
+```
+
+- `#` characters become the zero-padded frame number; `//` means relative to the `.blend`.
+- Pick the device and samples in a pre-render script (Cycles GPU setup in `references/batch-and-render.md`); without it Cycles uses whatever compute device that machine's saved preferences enable, and with `--factory-startup` that is the CPU.
+- List engine names with `blender -b -E help`; names differ across versions.
+- Render a single check frame and show it to the user before a long range or farm job.
+- Render image sequences, not a movie file, for anything long: a crash only loses one frame, and the sequence can be encoded afterwards with FFmpeg.
+
+## Never
+
+- Never overwrite the user's `.blend`, linked libraries or textures in place.
+- Never run scripts embedded in a `.blend` from an untrusted source (auto-run scripts stay off; never pass `-y` / `--enable-autoexec` for such files; pass `-Y` / `--disable-autoexec` to be explicit).
+- Never delete actions, bones or vertex groups without a backup and the user's approval.
+
+## Report back
+
+```
+Blender <version>   Files: n processed (ok / skipped / failed)
+Findings: <symptom> -> <cause> (evidence) -> <fix applied or proposed>
+Changed files: <output paths>      Renders: <path pattern, frames>
+Verification: values read back, check frame <path>
+Needs the user: mapping decisions, art direction, ...
+```

package/skills/blender-automation/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My Mixamo animation retargeted onto our character in Blender has twisted arms and the feet slide",
+    "Write a bpy script that sets roughness on every material across 40 .blend files and saves copies",
+    "Render frames 1 to 240 of this .blend headless on the Linux render box with the GPU",
+    "Imported FBX rig is at 0.01 scale and lying on its side, and the action does nothing in Blender 4.4",
+    "Dump every bone, its roll and its vertex group from this armature so I can see why the mesh tears"
+  ],
+  "should_not_trigger": [
+    "Animate a 3D rotating cube proof with Manim for my maths lecture",
+    "Build a three.js scene that loads a glTF model in the browser",
+    "Turn this PNG image sequence into an MP4 at 24 fps",
+    "Generate a 3D product render from a text prompt with an image model",
+    "Edit the drone footage into a 90-second travel video with music"
+  ]
+}

package/skills/blender-automation/references/batch-and-render.md

@@ -0,0 +1,77 @@
+# Batch edits and rendering
+
+## Driver script (one Blender process per file)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+mkdir -p out
+for f in assets/*.blend; do
+  blender -b --factory-startup "$f" --python-exit-code 1 -P edit.py -- "$PWD/out/$(basename "$f")" \
+    && echo "ok $f" || echo "FAILED $f"
+done
+```
+
+## edit.py pattern
+
+```python
+import bpy, sys
+out = sys.argv[sys.argv.index("--") + 1]
+
+changed = 0
+for mat in bpy.data.materials:
+    if not mat.use_nodes:
+        continue
+    bsdf = next((n for n in mat.node_tree.nodes if n.type == 'BSDF_PRINCIPLED'), None)
+    if bsdf:
+        bsdf.inputs["Roughness"].default_value = 0.6
+        changed += 1
+
+for ob in bpy.data.objects:
+    if ob.type == 'MESH' and not any(m.type == 'WEIGHTED_NORMAL' for m in ob.modifiers):
+        ob.modifiers.new("WeightedNormal", 'WEIGHTED_NORMAL')
+
+print(f"RESULT changed_materials={changed}")
+bpy.ops.wm.save_as_mainfile(filepath=out, copy=True)
+```
+
+Rules:
+- Socket names (such as "Roughness") and node types can change between versions; check the API docs for the installed version and fail loudly if a name is missing.
+- Prefer `bpy.data` edits over `bpy.ops`; when an operator is unavoidable, use `with bpy.context.temp_override(...)` to give it the context it needs.
+- Use `bpy.ops.wm.save_as_mainfile(..., copy=True)` so the open file name is not changed and originals are not touched.
+- Linked library data is read-only in the file that links it; edit the library file itself.
+
+## Cycles GPU pre-render script
+
+```python
+import bpy
+prefs = bpy.context.preferences.addons["cycles"].preferences
+prefs.compute_device_type = "OPTIX"   # or CUDA, HIP, METAL, ONEAPI, depending on hardware
+prefs.get_devices()
+for d in prefs.devices:
+    d.use = d.type != "CPU"
+scn = bpy.context.scene
+scn.render.engine = "CYCLES"
+scn.cycles.device = "GPU"
+scn.cycles.samples = 256
+scn.cycles.use_denoising = True
+```
+
+Use it with `blender -b shot.blend -P gpu.py -o /abs/renders/shot_#### -F PNG -a`. If no GPU device appears in `prefs.devices`, say so; do not silently fall back to a CPU render that will take hours.
+
+## Render settings from Python
+
+```python
+r = bpy.context.scene.render
+r.resolution_x, r.resolution_y, r.resolution_percentage = 1920, 1080, 100
+r.image_settings.file_format = "PNG"
+r.filepath = "//renders/shot_####"
+bpy.context.scene.frame_start, bpy.context.scene.frame_end = 1, 240
+bpy.ops.render.render(animation=True)
+```
+
+## Encode the sequence afterwards
+
+```bash
+ffmpeg -framerate 24 -i renders/shot_%04d.png -c:v libx264 -crf 18 -pix_fmt yuv420p shot.mp4
+```

package/skills/blender-automation/references/bpy-inspection.md

@@ -0,0 +1,91 @@
+# bpy inspection snippets
+
+Run with `blender -b file.blend --python-exit-code 1 -P inspect.py -- out.json`.
+
+## Scene and objects
+
+```python
+import bpy, json, sys
+out = sys.argv[sys.argv.index("--") + 1]
+scn = bpy.context.scene
+report = {
+    "blender": bpy.app.version_string,
+    "frame_range": [scn.frame_start, scn.frame_end], "fps": scn.render.fps / scn.render.fps_base,
+    "engine": scn.render.engine, "output": scn.render.filepath,
+    "objects": [{
+        "name": o.name, "type": o.type, "parent": o.parent.name if o.parent else None,
+        "location": list(o.location), "rotation": list(o.rotation_euler), "scale": list(o.scale),
+        "collections": [c.name for c in o.users_collection],
+    } for o in bpy.data.objects],
+}
+json.dump(report, open(out, "w"), indent=2)
+```
+
+## Armature, bones and pose
+
+```python
+arm = bpy.data.objects["Armature"]
+for b in arm.data.bones:            # rest data (edit-bone values, read-only here)
+    print(b.name, b.parent.name if b.parent else None, tuple(b.head_local), tuple(b.tail_local),
+          b.use_deform, b.use_connect, b.inherit_scale)
+for pb in arm.pose.bones:           # pose data
+    print(pb.name, pb.rotation_mode, [c.type for c in pb.constraints], tuple(pb.matrix_basis.to_euler()))
+```
+
+Bone roll is only exposed on edit bones: switch to Edit mode on the armature (`bpy.ops.object.mode_set(mode='EDIT')` with it active) and read `arm.data.edit_bones[name].roll`, then return to Object mode.
+
+## Vertex groups versus deform bones
+
+```python
+mesh = bpy.data.objects["Body"]
+deform = {b.name for b in arm.data.bones if b.use_deform}
+groups = {g.name for g in mesh.vertex_groups}
+print("groups without bone:", sorted(groups - deform))
+print("deform bones without group:", sorted(deform - groups))
+print("armature modifiers:", [(m.name, m.object.name if m.object else None) for m in mesh.modifiers if m.type == 'ARMATURE'])
+```
+
+## Actions and F-Curves (Blender 4.4+ layered actions)
+
+Actions hold layers, layers hold strips, and a keyframe strip holds one channelbag per slot. `Action.fcurves` was removed in 5.0.
+
+```python
+ad = arm.animation_data
+act, slot = ad.action, ad.action_slot
+print(act.name if act else None, slot.identifier if slot else None, [s.identifier for s in act.slots])
+
+from bpy_extras import anim_utils
+bag = anim_utils.action_get_channelbag_for_slot(act, slot)   # None if the slot has no keys
+for fc in bag.fcurves:
+    keys = fc.keyframe_points
+    print(fc.data_path, fc.array_index, len(keys), keys[0].co.x if keys else None, keys[-1].co.x if keys else None)
+```
+
+If `action_get_channelbag_for_slot` is missing in the installed version, walk it directly: `act.layers[0].strips[0].channelbag(slot)`.
+
+Remap bone names in data paths (after the user confirms the mapping):
+
+```python
+mapping = {"mixamorig:LeftArm": "upper_arm.L"}
+for fc in bag.fcurves:
+    for src, dst in mapping.items():
+        token = f'pose.bones["{src}"]'
+        if fc.data_path.startswith(token):
+            fc.data_path = fc.data_path.replace(token, f'pose.bones["{dst}"]', 1)
+```
+
+Assign an action and its slot:
+
+```python
+ad = arm.animation_data or arm.animation_data_create()
+ad.action = act
+if ad.action_slot is None and act.slots:
+    ad.action_slot = act.slots[0]
+```
+
+## NLA
+
+```python
+for t in ad.nla_tracks:
+    print(t.name, t.mute, [(s.name, s.action.name, s.frame_start, s.frame_end) for s in t.strips])
+```

package/skills/blender-automation/references/rig-and-retarget-checks.md

@@ -0,0 +1,23 @@
+# Rig and retarget checks
+
+Work top to bottom. For each, read the values with the inspection snippets; do not judge from a viewport screenshot alone.
+
+| # | Symptom | Check | Typical fix |
+|---|---|---|---|
+| 1 | Character tiny, huge, lying down, or root motion in wrong units | Armature and mesh object `scale` not 1, or `rotation_euler.x` near 1.5708 (FBX import) | On a copy, apply rotation and scale (`transform_apply(location=False, rotation=True, scale=True)`), or re-import FBX with Apply Transform or a unit scale the user confirms; re-check location keys after |
+| 2 | Every limb offset by the same amount after retarget | Rest poses differ (A-pose vs T-pose): compare `bone.matrix_local` of matching bones | Retarget with constraints in local or pose space and bake, or adjust the source rest pose to match before baking |
+| 3 | Limbs twist or rotate around the wrong axis | Edit-bone `roll` differs for matching bones | Match roll on the target only if it is not yet skinned or the user accepts re-weighting; otherwise retarget in world or pose space |
+| 4 | Some bones do not move | F-Curve data paths name bones that are not in the target | Rename bones or remap data paths with a confirmed mapping |
+| 5 | Bones move but rotate wrongly or jitter | Curves on `rotation_euler` but `rotation_mode` is `QUATERNION`, or the reverse; quaternion sign flips between keys | Set `rotation_mode` to match the curves, or convert and bake; fix sign flips by negating the quaternion on flipped keys |
+| 6 | Action assigned but nothing plays (4.4+) | `animation_data.action_slot` is None or its `target_id_type` does not match | Assign the right slot |
+| 7 | NLA or another action overrides the keys | NLA tracks not muted, action influence, or tweak mode | Mute or remove tracks on a copy; push the action to an NLA strip deliberately |
+| 8 | Pose ignores keys | Constraints (IK, Child Of, Copy Transforms) with influence 1 | Check each constraint's influence and target; bake visual transforms if the constraints are only for retargeting |
+| 9 | Mesh tears or parts stay behind | Vertex groups with no matching deform bone, `use_deform` off, Armature modifier missing or on the wrong object, or modifier order (Armature after a Subdivision) | Fix names and flags; move the Armature modifier to the top of the stack |
+| 10 | Creeping scale down a chain | `inherit_scale` and scale keys on parent bones | Remove scale keys that should not exist; set inherit scale as the rig design requires |
+| 11 | Foot sliding after retarget | Different leg lengths between rigs | Scale root motion by the leg-length ratio, or use IK for feet and bake |
+
+Verification after any fix:
+
+1. Read the changed values back from the saved copy.
+2. Render or capture three frames (first, middle, last of the action) from a fixed camera and compare with the source.
+3. Report key counts per bone before and after a bake; a bake should not drop channels unexpectedly.