AutoGineer
Generated banner for Qiime2 Amplicon
Generated logo for Qiime2 Amplicon

Qiime2 Amplicon

K-DenseCommunityCreated by K-Dense Inc.

  • Skill
  • Workflow
  • Science and research
  • MIT
  • Low risk
  • Has scripts
Download ZIP

From the author

Processes paired-end 16S amplicon reads into QIIME 2 ASVs and taxonomy with retained artifact provenance. Checks paired FASTQ manifests, primer orientation diagnostics, predicted post-trimming overlap, sample IDs, runtime versions and read retention, and guides selection of compatible taxonomic classifiers.
— the description by K-Dense Inc.

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured, validated workflow for processing demultiplexed, paired-end 16S amplicon reads using QIIME 2 (version 2026.7). It automates the import of FASTQ files, primer removal via Cutadapt, denoising with DADA2, and taxonomic classification. The workflow emphasizes data integrity by enforcing strict manifest formats, validating primer orientation, and maintaining artifact provenance throughout the analysis pipeline. It includes built-in quality control checks for read retention and sample consistency, ensuring that researchers can reliably move from raw sequences to taxonomic feature tables.

What it does

  • Imports paired-end FASTQ reads using a validated manifest format.
  • Performs primer removal and quality-based denoising using DADA2.
  • Generates taxonomic assignments using user-supplied compatible classifiers.
  • Validates input data, including sample IDs and primer orientation.
  • Tracks artifact provenance and generates retention statistics for quality assessment.
  • Produces standardized QIIME 2 artifacts (.qza/.qzv) for downstream ecological analysis.

When to use it

  • When processing 16S amplicon sequencing data in a QIIME 2 2026.7 environment.
  • When you need a reproducible pipeline that preserves artifact provenance.
  • When you have known primer sequences and expected insert lengths for your assay.
  • When you need to perform automated quality control on read retention and sample alignment.

Advantages

  • Reduces manual errors through automated validation of manifests and metadata.
  • Ensures reproducibility by maintaining full artifact provenance.
  • Provides clear diagnostic feedback on primer matching and read retention.
  • Integrates directly with standard QIIME 2 plugin workflows.

Usage examples

“Validate my 16S amplicon manifest and primer settings before running the full analysis.”
The skill performs a dry-run validation of the manifest structure, primer sequences, and truncation parameters to ensure compatibility before execution.
“Run the full 16S processing pipeline on my paired-end reads using a specific classifier.”
The skill executes the complete workflow, including import, trimming, denoising, and classification, outputting all results to a designated directory.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/k-dense-ai/qiime2-amplicon/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip qiime2-amplicon.zip -d .agents/skills

Documentation by K-Dense Inc.

QIIME 2 paired-end 16S amplicons

Use for a demultiplexed, paired-end 16S assay with known primers, quality encoding, expected insert length, and sample metadata. This bounded workflow imports reads, removes 5′ primers, denoises with DADA2, classifies ASVs using an explicitly supplied classifier, and retains .qza/.qzv provenance. Do not treat read counts as absolute cell counts or taxonomy assignments as strain identification.

Establish the assay before running

  • Confirm Phred+33, read orientation, primer sequences as sequenced in forward/reverse reads, and whether primers have already been removed. The bundled runner requires primers still present at the 5′ ends; it anchors Cutadapt matching and discards untrimmed pairs. Already trimmed reads need a direct import → DADA2 workflow with that omission recorded in provenance.

  • Choose truncation positions from actual per-base quality and error profiles. trunc-f/r are positions after primer removal. The expected maximum insert length also excludes primers. Require trunc_f + trunc_r - maximum_insert_length >= 12; use a margin for length variation. The check predicts geometrical overlap, not successful biological merging.

  • Choose a classifier whose reference database, taxonomic coverage, orientation and training approach fit the assay. Full-length classifiers are supported; primer-region-specific training is not mandatory. Match its scikit-learn version exactly to the installed environment (the official 2026.7 distribution pins 1.7.1). Record source URL, database version and checksum. QIIME's current data-resources page links externally hosted classifiers for 2026.4 and later; its older downloads are not automatically compatible. Do not automatically fetch an arbitrary “latest” classifier or reuse an incompatible serialized sklearn model. Load sklearn classifier artifacts only from trusted sources: QZA format validation does not make an untrusted serialized model safe.

  • Include extraction blanks, PCR negatives, and a mock community where available. The runner rejects empty FASTQs; preserve empty-control IDs separately and report them rather than silently deleting control evidence. Assess contamination before ecological interpretation.

Input files

Manifest is a tab-separated PairedEndFastqManifestPhred33V2 file with exactly these headers:

sample-id	forward-absolute-filepath	reverse-absolute-filepath
sample1	/data/sample1_R1.fastq.gz	/data/sample1_R2.fastq.gz

This is the helper's deliberately narrow manifest profile. Use actual tab characters, literal absolute paths visible to the runtime (expand environment variables before calling this helper), and one row per sample; no comment/directive rows or additional columns in this manifest. Do not reverse-complement R2 files. Sample metadata is a tab-separated file with first column sample-id, unique IDs matching the manifest, and optional #q2:types annotation. Include covariates and biological replicate IDs needed downstream. The helper checks metadata IDs and row structure; QIIME performs full metadata typing/directive validation during execution. Metadata used by actions persists in artifact provenance, so use de-identified biological replicate IDs.

Execute

The helper lives at scripts/amplicon_workflow.py. Commands below assume the skill directory is the working directory. First validate without QIIME. These example primers and lengths are illustrative, not universal assay settings:

python scripts/amplicon_workflow.py validate \
  --manifest manifest.tsv --metadata sample-metadata.tsv \
  --primer-f GTGYCAGCMGCCGCGGTAA --primer-r GGACTACNVGGGTWTCTAAT \
  --trunc-f 220 --trunc-r 200 --amplicon-max 300

Then run in the QIIME 2 2026.7 environment with a compatible classifier. This study-specific invocation is illustrative; choose lengths using a preceding quality inspection or pilot:

python scripts/amplicon_workflow.py run \
  --manifest manifest.tsv --metadata sample-metadata.tsv \
  --primer-f GTGYCAGCMGCCGCGGTAA --primer-r GGACTACNVGGGTWTCTAAT \
  --trunc-f 220 --trunc-r 200 --amplicon-max 300 \
  --classifier compatible-classifier.qza --threads 4 --output run01

run executes immediately, writes only to a fresh output directory, and stops on a failing QIIME command. It streams through every paired FASTQ record to catch mismatched IDs/order/counts, checks sequence/quality consistency and sample alignment, and profiles the first 1,000 read pairs for exact IUPAC primer matches. Low exact-match rates are warnings: Cutadapt allows mismatches, but a low rate can also indicate incorrect orientation, adapters, or already-trimmed data. At least one complete pair per sample must meet nominal post-primer truncation lengths. These length estimates subtract the stated primer lengths; they do not simulate Cutadapt indels or quality filtering, and do not establish that any pair will actually merge.

The runner uses --output-dir for plugin methods with evolving output sets, preserving Cutadapt statistics and DADA2 base-transition artifacts when supplied by the release. The 2026.7 table summary also produces feature-frequencies.qza and sample-frequencies.qza beside table.qzv. It records qiime-info.txt, commands.json, workflow.log, input QC, classifier checksum and output artifact checksums. It runs maximum-level QIIME artifact validation before reporting completion. See references/runtime-and-interpretation.md for the release-pinned runtime, actual validation scope, restart handling and scientific interpretation.

Inspect results before analysis

Open trimmed.qzv, table.qzv, and taxa.qzv in a local QIIME visualization environment or QIIME 2 View as appropriate for the data. Examine quality/length profiles, per-sample depth and dominant taxa. Retain original artifacts rather than replacing them with CSV/BIOM exports: exports do not retain the original provenance graph.

retention-qc.json compares raw pairs with DADA2 input and non-chimeric reads, so trimming losses remain visible. A <50% retained fraction is a review heuristic, not a universal rejection rule. Inspect the individual stages in stats/stats.tsv: filtering loss suggests quality/expected-error settings; loss after forward denoising includes reverse-denoising and merging failures; chimera loss warrants reviewing library quality and parameters. Investigate missing/zero samples and control behavior before rarefaction, diversity, or differential abundance. Those downstream analyses need a separate design decision; this skill does not choose a rarefaction depth automatically. The standalone retention stats.tsv subcommand knows only DADA2 input counts: it reports raw_pairs: null and names that denominator explicitly. It supports merged-only paired DADA2 statistics, as produced by this runner; it rejects retained-unmerged/concatenated-read statistics.

Primary references

The rolling documentation may describe a development release. Inspect qiime info and action --help in the exact installed environment before adapting the pinned runner to a later release.

Files

references/runtime-and-interpretation.md

Release-pinned runtime and interpretation

Installation and environment

This runner targets QIIME 2 2026.7, still the stable release selected by the official quickstart on 2026-10-01. The official distribution image is quay.io/qiime2/qiime2:2026.7 (the image naming changed from earlier amplicon releases). Use the official quickstart for its conda environment or container. A PyPI package with a similar name is not a replacement for the distribution's R, DADA2 and plugin environment. On Apple Silicon, the previously tested container uses Linux amd64 emulation; official conda instructions require x86-64/Rosetta, rather than an ARM build.

For example, mount a data directory at /data and this skill at /skill, and run the Python helper inside the container. Manifest absolute paths must be /data/..., not host-only paths. Ensure enough disk space for both image download/unpacking and working artifacts; artifact creation can copy/intermediately materialize the reads.

This installation example was checked against current documentation, not rerun during the 2026-10-01 refresh:

docker run --rm --platform linux/amd64 \
  -v "$PWD/data:/data" -v "$PWD/qiime2-amplicon:/skill:ro" \
  quay.io/qiime2/qiime2:2026.7 qiime info

qiime info and qiime dada2 denoise-paired --help in the target environment are the authoritative command contract. Rolling web documentation can already describe 2026.10.0.dev0 and Python rachis imports while an installed release has a different action signature. The runner uses the CLI and release check rather than relying on rolling Python import paths. Both trimming and DADA2 use --output-dir, preserving release-specific additional outputs. In 2026.7, feature-table summarize takes --m-metadata-file and produces --o-summary, --o-feature-frequencies, and --o-sample-frequencies; older tutorials using --m-sample-metadata-file and --o-visualization do not apply to this action. The helper checks the framework, q2cli and every used plugin's version line, rather than accepting an unrelated occurrence of 2026.7 in the environment report. Development/mixed releases fail preflight. This verifies reported package versions, not native-library health.

Verified 2026.7 action contract

The 2026.7.0 plugin registrations and implementations were checked alongside rolling docs:

ActionContract used by this workflow
tools importSampleData[PairedEndSequencesWithQuality], format PairedEndFastqManifestPhred33V2; .qza output. The underlying V2 manifest is QIIME metadata; this helper accepts a narrower literal-path three-column profile.
cutadapt trim-paireddemultiplexed_sequences, IUPAC front_f/front_r anchored with ^, discard_untrimmed, cores; outputs trimmed_sequences and stats (ImmutableMetadata). With both primers supplied, default pair filtering discards a pair if either mate is untrimmed.
demux summarizedata input and visualization output; positional quality plots sample reads, rather than verifying all per-base qualities.
dada2 denoise-paireddemultiplexed_seqs, positive trunc_len_f/r, zero trim_left_f/r, min_overlap, n_threads; outputs table, representative sequences, denoising stats and base-transition stats.
feature-table summarizeA pipeline accepting table and metadata; produces two ImmutableMetadata artifacts and a summary visualization.
feature-classifier classify-sklearnTaxonomicClassifier and sequence reads, n_jobs; output FeatureData[Taxonomy]. Default confidence is 0.7; read_orientation=auto selects an orientation using the first 100 reads.
taxa barplotFrequency table, taxonomy and metadata; all table feature IDs need taxonomy annotations. barplot remains supported; the separate barplot2 is experimental.
tools export / tools validateExport the DADA2 stats artifact to stats.tsv; validate each QZA with positional artifact path and --level max. Exports omit artifact provenance.

The fixture additionally imports FeatureData[Sequence] and headerless FeatureData[Taxonomy] using HeaderlessTSVTaxonomyFormat, then calls feature-classifier fit-classifier-naive-bayes with reference_reads and reference_taxonomy to produce a TaxonomicClassifier. These are local CLI/plugin APIs, not hosted analysis endpoints.

Defaults matter: the runner inherits Cutadapt error rate 0.1, indel matching, one removal pass and no quality trimming; DADA2 uses maximum expected errors 2 per mate, trunc_q=2, independent denoising, consensus chimera removal, zero merge mismatches and retain_unmerged=False. DADA2's minimum overlap API permits 4 or more bases, but this helper deliberately requires at least 12. retain_unmerged=True produces linked sequences and adds concatenated counts; those are outside this helper's merged-ASV retention contract. Samples with zero retained frequency remain represented by the default retain_all_samples=True. The official distribution pins Cutadapt 5.2, R 4.5.2 and DADA2 1.38.0; do not independently upgrade them in the pinned environment.

Classifiers and provenance

Supply a trusted TaxonomicClassifier with suitable database coverage, training choices and compatible QIIME/scikit-learn environment. Full-length training is supported; the official resource page no longer requires region-specific classifiers. Record database citation, any region extraction primers, training parameters, confidence threshold, source URL, artifact UUID and SHA-256. Keep the training artifact lineage when available. QIIME's ZIP/schema validation does not establish the safety of an untrusted serialized sklearn model.

If no matching classifier exists, train within the target distribution from an appropriate curated reference sequence/taxonomy pair using its feature-classifier actions. A classifier trained on a tiny test reference only validates execution and label plumbing; it says nothing about taxonomic accuracy on biological samples. Do not silently substitute such a test reference for a real database.

The resulting QZA files preserve QIIME action provenance. commands.json supplements this with actual CLI arguments; the runner also records release information and hashes. Copying only exported FASTA/TSV/BIOM loses the artifact provenance graph. Retain the original FASTQs and classifier.

Read retention and assay interpretation

The helper's overlap formula assumes fixed positive DADA2 truncation positions after primer removal, no additional trim-left, and an upper bound on primer-free amplicon length. Use the longest plausible insert rather than its mean. ITS and other highly variable-length amplicons need a different strategy; applying a 16S fixed-length workflow can preferentially exclude taxa.

Exact primer-prefix matching profiles only the first 1,000 pairs. It is a diagnostic, not a Cutadapt simulator: Cutadapt allows mismatches/indels according to its defaults. Anchoring assumes primers begin at base one; staggered primers or remaining sequencing adapters need explicit adaptation. The helper inspects every record for paired IDs, sequence/quality lengths and raw counts. Phred+33 character validation cannot establish that the acquisition actually used Phred+33 rather than Phred+64; obtain that fact from sequencing metadata.

Use stats/stats.tsv to localize losses. Raw → DADA2 input includes primer trimming; input → filtered reflects quality/length/error limits; denoised is the forward-denoised count, so denoised → merged includes both reverse-denoising and merging losses; merged → non-chimeric tests chimera removal. The runner's 50% retention warning is a review heuristic. Do not automatically relax quality settings until every sample passes. Compare loss patterns by batch, treatment, read quality, and controls, and report samples excluded from downstream analyses.

ASVs are denoised marker-gene sequences, not guaranteed species or organisms. 16S copy number, primer bias and contamination affect abundance. Taxonomic confidence does not remove ambiguity in a short region. Preserve unassigned features and investigate them before choosing exclusions. Classifier confidence is a model threshold, not a calibrated probability of species identity; automatic orientation detection does not establish the assay's biological orientation. This fixed-length workflow also assumes no unresolved opposite-primer read-through; short inserts can violate that assumption even when the maximum-length overlap check passes.

Restart behavior

The runner stops at the first failed command and leaves its log, command list and completed QZA artifacts intact. It requires a new output directory for an entire rerun. To resume a specific step, use the recorded QIIME command with validated preceding artifacts and a new output path, keeping the original parameters unless the failure evidence justifies a change. A changed trimming or DADA2 parameter produces a different analysis, not an interchangeable continuation.

Earlier native integration evidence

The following is the pre-existing bounded native-run record. The 2026-10-01 refresh verified current official documentation/source and reran portable input/retention tests; it did not rerun QIIME, install its distribution, or independently revalidate the archived container digest. The example workflow is therefore source-verified for the pinned release, with the earlier native evidence bounded as described below.

The bounded regression used the official quay.io/qiime2/qiime2:2026.7 image at digest sha256:ffde217254fe71bc3ace7f17d4ee5efebbad4f81dab52b6af8aee124ebc713c8, under Linux amd64 emulation on Apple Silicon. qiime info reported Python 3.12.13, rachis/q2cli 2026.7.0, and the relevant plugins at 2026.7.0.

Ten nonempty paired samples, each with 100 pairs, derive from the official q2-dada2 regression fixture at commit 8bbf5158d6c71b37b57a0e1f6e2b1cb69b9e96d7. Synthetic Q40 primer prefixes were added so the real Cutadapt stage restores the original upstream reads. The original empty BLANK control is documented separately. DADA2 recovered exactly the expected 18 ASV sequences and 243 non-chimeric reads; every sample's input, filtered, denoised, merged and non-chimeric counts matched the upstream expected table. Two samples have zero retained reads, deliberately exercising retention reporting rather than silently removing those samples from QC.

The run trained a tiny classifier inside the same environment using the expected sequences and invented SyntheticFixture labels. Real classify-sklearn assigned those domain labels to all 18 ASVs, and table/taxonomy visualizations were produced. This verifies artifact and classification plumbing, not biological taxonomic accuracy or a production database's suitability.

The initial run exposed the changed 2026.7 feature-table summary arguments described above. After correcting the runner, execution resumed from the already completed DADA2 artifacts; input import, trimming and denoising were not rerun. The runtime evidence retains both the failed and corrected commands and the original artifact provenance. In a repository checkout, tests/qiime2-amplicon/run_integration.py --output FRESH_DIRECTORY stages the bundled licensed fixtures and runs the corrected workflow. Its --verify-only RESULTS_DIRECTORY mode independently checks exact stage counts, ASV sequences, taxonomy feature IDs and synthetic labels, and artifact action provenance. The portable pytest suite uses only the standard library and does not launch or download the large QIIME distribution.

All 10 generated QZA artifacts passed maximum-level QIIME validation. After three sequential checks had passed, the remaining independent read-only checks used at most three identical containers concurrently; an interrupted fourth check was recorded and rerun. The final retention report was generated with the same bundled retention and digest functions. The standalone integration verifier passed all count, sequence, taxonomy identity and action-provenance checks. These results establish regression behavior on the small fixture, not DADA2 error-model calibration or taxonomic accuracy for a new biological study.

Official sources reviewed

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

The author says: Python 3.10+ for the standard-library validation helper; QIIME 2 2026.7 distribution with cutadapt, dada2, demux, feature-table, feature-classifier, taxa and types plugins for execution. Install through the official conda/container distribution, not PyPI. Requires a compatible trusted classifier and network for installation/reference downloads.

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
K-Dense Inc.
Publisher
K-Dense (Community)
Source
K-Dense-AI/scientific-agent-skills · skills/qiime2-amplicon · commit a25cf9e
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE.md)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by K-Dense Inc. or K-Dense.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download qiime2-amplicon.zip