How to use the QIIME 2 16S amplicon agent skill

What the skill makes the agent do

The skill guides the agent through a fixed sequence: import paired FASTQ reads, remove the 5′ primers, denoise with DADA2 into ASVs (exact sequence variants), and assign taxonomy using a classifier you supply. Along the way it keeps .qza and .qzv artifacts so results can be traced back to their inputs.

Before running anything, the agent checks the paired FASTQ manifest, primer orientation, predicted overlap after trimming, sample IDs, runtime versions and read retention. It also helps choose a classifier that is compatible with your assay. The skill assumes a known assay: Phred+33 quality encoding, primers still present in the reads, and a known expected insert length.

• Validates the manifest, metadata and primer settings without QIIME.
• Runs the QIIME 2 steps and stops if a QIIME command fails.
• Writes provenance files such as qiime-info.txt, commands.json, workflow.log and checksums of classifier and output artifacts.
• Produces retention-qc.json so trimming and denoising losses stay visible.

How to install the qiime2-amplicon skill

Download the skill ZIP from this page and unzip it. For a personal setup, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.

The skill runs code and needs QIIME 2 installed separately. Install QIIME 2 through the official conda environment or container, not from PyPI. A PyPI package with a similar name is not a replacement for the distribution's R, DADA2 and plugin environment.

• Required QIIME 2 plugins: cutadapt, dada2, demux, feature-table, feature-classifier, taxa and types.
• Python 3.10 or newer for the standard-library validation helper.
• Network access is needed for installation and for downloading reference data.

Prepare your inputs

The manifest must be a tab-separated file with exactly these headers: sample-id, forward-absolute-filepath and reverse-absolute-filepath. Use one row per sample and absolute paths that the runtime can see. Do not reverse-complement R2 files.

The sample metadata file is also tab-separated. Its first column must be sample-id, and its IDs must match the manifest. Use de-identified biological replicate IDs, because metadata used by actions is stored in artifact provenance.

• Manifest: tab-separated, three headers, one row per sample, no comment rows or extra columns.
• Metadata: first column sample-id, unique IDs matching the manifest, optional #q2:types line.
• Include extraction blanks, PCR negatives and a mock community if you have them. The runner rejects empty FASTQ files, so record empty control IDs separately rather than deleting them.

How to trigger the skill with natural requests

You do not need to type the skill name in most cases. Describe the job and point the agent at your files. Say that the reads are paired-end 16S, name the primers as sequenced, and state where the classifier is. The agent should then check the assay before running.

If you only want checks, say so. The validation step runs without QIIME and is a good first request.

• Check my paired-end 16S reads in /data/run01 with primers GTGYCAGCMGCCGCGGTAA and GGACTACNVGGGTWTCTAAT before we run anything.
• Process these demultiplexed 16S reads into ASVs and taxonomy using my trusted classifier file compatible-classifier.qza.
• Explain whether my truncation lengths leave enough overlap for these amplicons.
• Summarize retention-qc.json and tell me which stage lost the most reads.

Run the validation and the workflow

Start by validating your setup. The primers and lengths shown below are illustrative examples from the skill, not universal settings. Choose your own truncation lengths from a quality inspection or pilot run.

The run command executes immediately and writes only to a fresh output directory. Open trimmed.qzv, table.qzv and taxa.qzv in a QIIME visualization environment or QIIME 2 View, and keep the original artifacts rather than replacing them with CSV or BIOM exports.

Read the quality checks and results

Trimming loss shows up in retention-qc.json, which compares raw pairs with DADA2 input and non-chimeric reads. A retained fraction below 50% is a review heuristic, not a rejection rule. Check stats/stats.tsv to see which stage lost reads: filtering loss points to quality or expected-error settings, while chimera loss suggests reviewing library quality and parameters.

Do not read counts as absolute cell numbers, or taxonomy as confirmed strain identity. The skill does not choose a rarefaction depth for you, so decide that separately before diversity or differential abundance analysis.

• Missing or zero-read samples and control behaviour should be investigated before downstream analysis.
• Low primer match rates are warnings. They can mean wrong orientation, adapters or already-trimmed reads.

Safety notes: scripts and network use

This skill runs scripts and uses the network. The helper is a Python script in scripts/ and the agent may install QIIME 2 and download reference data. Review the commands the agent proposes before approving them, and confirm the output directory is one you want written to.

Classifier files need care. Load scikit-learn classifier artifacts only from trusted sources, because a QZA format check does not make a serialized model safe. Do not let the agent fetch an arbitrary latest classifier automatically. Record the source URL, database version and checksum for the classifier you use.

• Do not use sensitive human data with an unvetted classifier file.
• The scikit-learn version of the classifier must match your installed QIIME 2 environment exactly.