How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/mbhall88/skillz --skill seqkitBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
seqkit
seqkit is a fast, streaming toolkit for fastx files (FASTA or FASTQ). It has 39 subcommands covering nearly every routine sequence-file operation. Before writing a script that reads a fastx file, check the routing table below.
Requires seqkit on $PATH. If it is not there, this skill does not apply — fall back to scripting.
Rules
- Write long flags. Short flags mean different things in different
subcommands: -s is --by-seq in rmdup but --rand-seed in sample, --step in sliding, and --pattern in mutate. -p is --pattern in grep but --point in mutate. Long flags are unambiguous and self-documenting. See references/traps.md for the collision table, needed when reading someone else's command.
- `seqkit <cmd> --help` is the authority on whether a flag exists. Never
assume a flag from another subcommand transfers. This document does not list flags on purpose — --help cannot go stale, and published seqkit docs demonstrably do.
- If it isn't fastx, it isn't seqkit. Interval arithmetic, BAM
manipulation, alignment, and tabular wrangling are other tools' jobs. See references/boundaries.md.
Leave global flags (-j/--threads, -w/--line-width, --id-regexp) at their defaults unless the user asks.
Routing table
⚠ marks a subcommand with a documented trap — read its entry in references/traps.md before using it.
Inspect and summarise
| Want to... | Command |
|---|---|
| Count records, total bases, min/max/mean length, GC%, Q20/Q30 | seqkit stats ⚠ (lengths and GC include gaps) |
| Get N50, L50, or any Nx | seqkit stats --all --tabular -N 50,90 ⚠ |
| Get machine-readable stats for downstream processing | seqkit stats --tabular ⚠ |
| Get per-record length, GC, name, or average quality as a table | seqkit fx2tab ⚠ |
| Find records containing ambiguous or unexpected bases | seqkit fx2tab --alphabet ⚠ |
| Get a per-sequence MD5 hash | seqkit fx2tab --seq-hash ⚠ |
| Tabulate several files at once, tagging each row with its source file (2.14+) | seqkit fx2tab --file-name ⚠ |
| Prove two files contain the same sequences, any order or strand | seqkit sum ⚠ |
| Prove two files contain the same records, IDs included (2.14+) | seqkit sum --include-id ⚠ |
| Watch length/quality/GC distributions while a pipeline runs | seqkit watch |
| Get BAM record statistics or histograms | seqkit bam |
Filter and subset
| Want to... | Command |
|---|---|
| Keep sequences above/below a length | seqkit seq --min-len / --max-len ⚠ |
| Keep reads above an average quality | seqkit seq --min-qual ⚠ |
| Filter and transform in one pass (2.13+) | seqkit seq --f-pattern ⚠ |
| Pull out records by ID, from a list | seqkit grep --pattern-file ⚠ (matches the whole ID; use --use-regexp for partial) |
| Pull out records by ID, preserving the list's order | seqkit faidx --region-file ⚠ |
| Take the first N records | seqkit head |
| Take the first N bases' worth of records | seqkit head --length 2G |
| Take records 101-200, or the last 100 | seqkit range --range |
| Take a random subset | seqkit sample2 (2.13+) ⚠ |
| Extract a region by coordinates | seqkit subseq --region ⚠ |
| Extract regions listed in a BED or GTF file | seqkit subseq --bed / --gtf ⚠ |
| Extract features plus flanking sequence | seqkit subseq --gtf --up-stream ⚠ |
| Extract a named region from an indexed FASTA | seqkit faidx ⚠ |
| Pull out the first genome from a multi-strain file by name prefix | seqkit head-genome |
Search
| Want to... | Command |
|---|---|
| Find records whose ID matches a pattern | seqkit grep --use-regexp ⚠ |
| Find records containing a subsequence or motif | seqkit grep --by-seq ⚠ |
| Find records containing a motif, allowing mismatches | seqkit grep --by-seq --max-mismatch ⚠ |
| Search with IUPAC/degenerate bases | seqkit grep --by-seq --degenerate ⚠ |
| Get the coordinates of every motif match | seqkit locate ⚠ |
| Get motif matches as BED or GTF | seqkit locate --bed / --gtf ⚠ |
| Scan for restriction sites from a FASTA of motifs | seqkit locate --degenerate --pattern-file ⚠ |
| Do in-silico PCR from a primer pair | seqkit amplicon ⚠ |
| Locally align short queries into long sequences | seqkit fish ⚠ |
Convert and tabulate
| Want to... | Command |
|---|---|
| Convert FASTQ to FASTA | seqkit fq2fa |
| Recover FASTQ (with qualities) for sequences you only have as FASTA | seqkit fa2fq |
| Turn fastx into a TSV for downstream tools | seqkit fx2tab ⚠ |
| Turn a TSV back into fastx | seqkit tab2fx |
| Convert FASTQ quality encoding (Solexa/Illumina/Sanger) | seqkit convert |
| Translate DNA/RNA to protein, any genetic code, any frame | seqkit translate |
| Reverse complement | seqkit seq --reverse --complement ⚠ |
| Strip gaps from an alignment | seqkit seq --remove-gaps ⚠ |
| Unwrap FASTA to one line per sequence | seqkit seq --line-width 0 ⚠ |
| Extract just the IDs or just the sequences | seqkit seq --name --only-id / --seq ⚠ |
Set operations and deduplication
| Want to... | Command |
|---|---|
| Remove duplicate records by ID or by sequence | seqkit rmdup ⚠ (--by-seq also collapses reverse complements) |
| Get a report of which records were duplicated | seqkit rmdup --dup-num-file ⚠ |
| Find sequences shared across several files | seqkit common ⚠ |
| Re-pair paired-end reads, dropping or saving singletons | seqkit pair ⚠ |
| Join sequences with the same ID across files | seqkit concat ⚠ |
| Repeat each record N times | seqkit duplicate |
Split and sample
| Want to... | Command |
|---|---|
| Split into N files, or files of N records | seqkit split2 --by-part / --by-size ⚠ |
| Split into one file per record, named by ID | seqkit split2 --by-size 1 --seqid-as-filename ⚠ |
| Split by ID, by a regex on the header, or by region | seqkit split ⚠ |
| Split paired-end FASTQ, keeping pairs together | seqkit split2 --read1 --read2 ⚠ |
| Take a random sample of records | seqkit sample2 (2.13+) ⚠ |
| Chop a sequence into fixed-size windows | seqkit sliding |
| Merge sliding windows back into intervals | seqkit merge-slides |
Edit and reorder
| Want to... | Command |
|---|---|
| Rewrite headers with a regex | seqkit replace ⚠ |
| Substitute, mask, or delete bases by regex (FASTQ from 2.14+) | seqkit replace --by-seq ⚠ |
| Rewrite headers from a TSV lookup table | seqkit replace --kv-file ⚠ |
| Number records sequentially, or stamp the filename into the header | seqkit replace with {nr} / {fbne} ⚠ |
| Make duplicate IDs unique | seqkit rename ⚠ |
| Introduce point mutations, insertions, or deletions | seqkit mutate ⚠ |
| Rotate a circular genome to a new origin | seqkit restart |
| Sort by ID, length, or sequence | seqkit sort ⚠ |
| Shuffle record order | seqkit shuffle ⚠ |
Streaming and repair
| Want to... | Command |
|---|---|
| Repair a truncated or malformed FASTQ, skipping bad records | seqkit sana |
| Stream fastx files as they appear in a directory | seqkit scat |
| Feed a long list of input files | any command, with --infile-list |
References
- references/traps.md — behaviours that produce plausible
but wrong output, or exhaust memory. Indexed by subcommand.
- references/recipes.md — multi-command compositions
where the composition is the insight.
- references/boundaries.md — what seqkit does not do,
and what does it instead.
Verified against seqkit v2.14.0. If a command here is unknown to your seqkit, it is older — check seqkit version.

