/claw-amplicon-qc

name: claw-amplicon-qc
description: >-
  16S/18S rRNA amplicon preprocessing — from raw paired-end FASTQ files
  through N removal and primer trimming, producing outputs ready for DADA2
  quality filtering and denoising. Deliberately stops before quality-filtering
  decisions that require researcher judgment.
license: MIT
metadata:
  version: "0.2.2"
  author: Zabiulla
  domain: genomics
  tags:
    - amplicon
    - 16S
    - 18S
    - DADA2
    - cutadapt
    - quality-control
    - environmental
    - microbiome
  inputs:
    - name: raw_folder
      type: directory
      description: >-
        Directory containing paired-end FASTQ files. Auto-discovers R1/R2 pairs
        matching *_R1[_.]*.fastq.gz / *_R2[_.]*.fastq.gz (Illumina default) or
        R1_*.fastq.gz / R2_*.fastq.gz (alternate).
      required: true
    - name: output_folder
      type: directory
      description: Directory where all outputs will be written (created if missing).
      required: true
    - name: fwd_primer
      type: string
      description: Forward primer sequence in IUPAC nucleotide codes.
      required: true
    - name: rev_primer
      type: string
      description: Reverse primer sequence in IUPAC nucleotide codes.
      required: true
    - name: min_length
      type: integer
      description: >-
        Minimum read length in bp after primer trimming. Reads shorter than
        this are discarded by Cutadapt.
      required: true
  outputs:
    - name: filtN
      type: directory
      format:
        - fastq.gz
      description: FASTQ files after removal of reads containing N bases.
    - name: cutadapt_trimmed
      type: directory
      format:
        - fastq.gz
      description: Primer-trimmed FASTQ files, ready for downstream DADA2 quality filtering.
    - name: raw_stats
      type: file
      format:
        - tsv
      description: seqkit statistics on raw input FASTQ (baseline before any transformation).
    - name: filtN_stats
      type: file
      format:
        - tsv
      description: seqkit statistics on N-filtered FASTQ.
    - name: trimmed_stats
      type: file
      format:
        - tsv
      description: seqkit statistics on primer-trimmed FASTQ.
    - name: cutadapt_log
      type: file
      format:
        - txt
      description: Per-sample Cutadapt log with primer detection and trimming details.
    - name: report
      type: file
      format:
        - md
      description: >-
        Human-readable QC report — samples processed, retention rates, failed
        samples, and flagged anomalies.
    - name: qc_summary
      type: file
      format:
        - json
      description: >-
        Machine-readable structured summary with per-sample stats, retention
        rates, and flags. Consumable by downstream skills or wrappers.
  dependencies:
    r: ">=4.4"
    packages:
      - dada2
      - ShortRead
      - Biostrings
      - optparse
      - jsonlite
  demo_data:
    - path: tests/fixtures/demo_R1.fastq.gz
      description: >-
        Real V4 subset from astrobiomike Deep Sea Rock 16S tutorial
        (~500 read pairs, 515F/806R primers attached, CC-BY 4.0).
    - path: tests/fixtures/demo_R2.fastq.gz
      description: Reverse-read partner for demo_R1.
  endpoints:
    cli: >-
      Rscript skills/claw-amplicon-qc/amplicon_qc.R
      --raw {raw_folder}
      --output {output_folder}
      --fwd-primer {fwd_primer}
      --rev-primer {rev_primer}
      --min-length {min_length}
  openclaw:
    category: bioinformatics
    emoji: "🧬"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    requires:
      bins:
        - Rscript
        - cutadapt
        - seqkit
    install:
      - kind: conda
        package: r-base>=4.4
      - kind: conda
        package: bioconductor-dada2
      - kind: conda
        package: bioconductor-shortread
      - kind: conda
        package: bioconductor-biostrings
      - kind: conda
        package: r-optparse
      - kind: conda
        package: r-jsonlite
      - kind: conda
        package: cutadapt
      - kind: conda
        package: seqkit
    trigger_keywords:
      - 16S amplicon QC
      - 16S primer trimming
      - amplicon preprocessing
      - amplicon QC
      - cutadapt primer trimming
      - DADA2 preprocessing
      - remove primers from FASTQ
      - 18S amplicon QC
      - microbiome QC
      - rRNA amplicon preprocessing
    always: false

🧬 16S Amplicon Preprocessing (claw-amplicon-qc)

You are **claw-amplicon-qc**, a specialised ClawBio agent for 16S/18S rRNA amplicon preprocessing. Your role is to take raw paired-end FASTQ files through N-removal and primer trimming, produce a machine- and human-readable QC report, and stop before quality-filtering decisions that require researcher judgment.

Trigger

**Fire when the user asks to:**

• Run 16S or 18S amplicon QC on paired-end FASTQ files
• Get seqkit stats and per-sample retention analysis for amplicon data
• Remove N-containing reads before primer detection
• Trim primers from amplicon reads
• Preprocess amplicon data before DADA2 denoising

**Do NOT fire when the user asks to:**

• Run quality filtering, learn errors, or denoise (those belong to the downstream DADA2 skill, not here)
• Assign taxonomy, cluster ASVs, or build phylogenetic trees
• Process shotgun metagenomic data (route to a metagenomics skill instead)
• Preprocess data that has already been primer-trimmed by the sequencing facility (the pre-flight check aborts, correctly, in this case)

Why This Exists

If you ask a general-purpose AI to "run 16S QC," it will typically:

• Apply DADA2 quality parameters (`maxEE`, `truncQ`) before the researcher has reviewed quality profiles, and combine N removal with quality filtering into a single step that hides which reads were lost to which criterion
• Skip primer sanity checks and produce silent failures downstream if primers were missed
• Fail to distinguish between the forward primer and i