Terminal
Terminal/Skill
Guides building and running bioinformatics pipelines such as alignment and variant calling on AWS HealthOmics, from workflow code to results.
By Amazon Web Services
Works with
npx skills add awslabs/hcls-agent-skills --skill bioinformatics-on-healthomicsEnd-to-end skill for creating, deploying, and running bioinformatics workflows on AWS HealthOmics. Designed for users who may not be deeply technical — the agent guides through every decision with clear explanations.
When guiding a user through a HealthOmics bioinformatics workflow, follow this order:
AWS HealthOmics is a fully managed service that runs genomics workflows. You provide:
HealthOmics handles compute provisioning, scheduling, and output collection.
omics.amazonaws.com is requiredBefore starting, verify:
aws-healthomics power)Ask the user what they want to accomplish. Common analysis types:
| Analysis Type | Common Tools | Input | Output |
|---|---|---|---|
| Quality Control | FastQC, MultiQC, fastp | FASTQ | QC reports, trimmed FASTQ |
| Alignment | BWA-MEM2, STAR, minimap2, bowtie2 | FASTQ + Reference | BAM/CRAM |
| Variant Calling | GATK HaplotypeCaller, DeepVariant, Strelka2, FreeBayes | BAM + Reference | VCF/gVCF |
| Structural Variants | Manta, DELLY, LUMPY, Sniffles | BAM + Reference | VCF |
| RNA-Seq | STAR + featureCounts, Salmon, kallisto | FASTQ + Reference/Index | Counts matrix |
| Methylation | Bismark, bwa-meth | FASTQ + Reference | Methylation calls |
| Variant Annotation | VEP, SnpEff, ANNOVAR | VCF + Databases | Annotated VCF |
| Joint Genotyping | GATK GenomicsDBImport + GenotypeGVCFs | gVCFs | Joint VCF |
| Somatic Calling | Mutect2, VarScan2, Strelka2-somatic | Tumor/Normal BAMs | Somatic VCF |
Based on the user's stated goal, recommend a pipeline of tools. Example combinations:
Whole Genome Sequencing (germline):
RNA-Seq differential expression:
Targeted panel / Exome:
Always explain WHY each tool is recommended and ask for confirmation before proceeding.
Ask the user's preference:
If the user has no preference, default to WDL 1.1 for simpler pipelines and Nextflow DSL2 for complex multi-sample scatter-gather patterns.
For each tool in the pipeline, find container images in this priority order:
For each tool, search for the latest stable image:
quay.io/biocontainers/<tool>:<version>--<hash>public.ecr.aws/biocontainers/<tool>:<version>broadinstitute/gatk:<version>, staphb/<tool>:<version>HealthOmics requires containers in private ECR. Use pull-through cache to automatically mirror public images.
Use the HealthOmics MCP CreatePullThroughCacheForHealthOmics tool:
upstream_registry as docker-hub, quay, or ecr-publicecr_repository_prefixquay and ecr-public: no credentials neededdocker-hub: a credential_arn is required (see below)Docker Hub rate-limits anonymous pulls. To use Docker Hub with pull-through cache,
store credentials in Secrets Manager and pass the ARN as credential_arn:
aws kms create-key → save the ARNaws secretsmanager create-secret --kms-key-id <KEY> --secret-string '{"username":"...","password":"..."}' → save the secret ARNcredential_arn to CreatePullThroughCacheForHealthOmicsIf the user has no Docker Hub account, prefer quay.io/biocontainers (no auth needed).
To verify the setup, use ValidateHealthOmicsECRConfig which checks all pull-through
cache rules, registry permissions, and repository templates.
To list existing rules and their HealthOmics usability, use ListPullThroughCacheRules.
Use the HealthOmics MCP CheckContainerAvailability tool with initiate_pull_through: true
to confirm each container is accessible. This verifies the image exists, checks HealthOmics
access permissions, and can trigger the initial pull-through.
To copy a specific image from an upstream registry to private ECR with HealthOmics
permissions, use CloneContainerToECR with the source image reference (supports
Docker Hub shorthand, quay.io, and public.ecr.aws formats).
For workflows referencing public registry URIs, create a container registry map so HealthOmics redirects pulls to your private ECR.
Use the HealthOmics MCP CreateContainerRegistryMap tool:
include_pull_through_caches: true to auto-discover HealthOmics-usable cachesadditional_registry_mappings or image_mappings for overridesCreateAHOWorkflow via the container_registry_map
parameter, or saved to S3 and referenced via container_registry_map_uriGenerate the workflow definition based on the chosen tools and language. Use steering documentation best practices in healthomics power
workflow/
main.wdl # Top-level workflow
tasks/
fastqc.wdl # Individual task definitions
bwa_mem2.wdl
gatk_hc.wdl
structs/
sample.wdl # Struct definitions
parameters.json # Example parameters
README.md # Documentation
workflow/
main.nf # Entry point
nextflow.config # Configuration
modules/
fastqc.nf # Process definitions
bwa_mem2.nf
gatk_hc.nf
conf/
healthomics.config # HealthOmics-specific config
nextflow_schema.json # Input schema (nf-schema)
parameters.json # Example parameters
README.md # Documentation
/mnt/workflow/pubdir as base~{var} interpolation and <<< >>> command delimitersset -eu in all command blocksFor WDL/CWL workflows, use the HealthOmics MCP LintAHOWorkflowDefinition or
LintAHOWorkflowBundle tool to validate before deployment.
On first use, set up the required AWS infrastructure. Ask the user for each component or offer to create it.
Create an S3 bucket for workflow inputs, outputs, and optional call caching:
aws s3 mb s3://<BUCKET_NAME> --region <REGION>
The bucket is used for:
Create a service role for HealthOmics:
# Create the role with HealthOmics trust policy
aws iam create-role \
--role-name <ROLE_NAME> \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "omics.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}'
The role needs:
omics.amazonaws.coms3:GetObject, s3:PutObject, s3:ListBucket, s3:GetBucketLocation on the bucketecr:BatchGetImage, ecr:GetDownloadUrlForLayer, ecr:BatchCheckLayerAvailabilitylogs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents on /aws/omics/*Ask the user about call caching. Explain that call caching allows HealthOmics to skip re-running tasks whose inputs haven't changed — this is especially valuable during iterative workflow development where some steps (like alignment) succeed but later steps (like variant calling) need tuning.
Ask the user which cache behavior they prefer:
CACHE_ON_FAILURE (recommended for development) — Caches results from successful tasks when a run fails. On the next run, tasks with identical inputs are skipped. Ideal for iterative development: fix a failing step, re-run, and only the changed/failed tasks execute again. Upstream steps that already succeeded are served from cache.
CACHE_ALWAYS — Caches results from every run regardless of outcome. Useful for production pipelines where you re-run the same workflow on new samples and want to skip any tasks that happen to have identical inputs (e.g., reference indexing).
Create the run cache using CreateAHORunCache:
cache_behavior — the user's choice abovecache_s3_location — an S3 prefix for cache storage (e.g., s3://<BUCKET>/healthomics-cache/)name — descriptive name (e.g., "dev-cache" or "production-cache")Save the returned cache_id for use in runs.
Save settings to .healthomics/config.toml:
omics_iam_role = "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>"
run_output_uri = "s3://<BUCKET>/healthomics-outputs/"
run_storage_type = "DYNAMIC"
cache_id = "<CACHE_ID>"
cache_behavior = "CACHE_ON_FAILURE" # or "CACHE_ALWAYS"
cache_s3_location = "s3://<BUCKET>/healthomics-cache/"
aws_region = "<REGION>"
Package and deploy the workflow to HealthOmics using the MCP tools:
Package the workflow — Use PackageAHOWorkflow:
main_file_content to the path of your main workflow file (e.g., ./workflow/main.wdl)main_file_name appropriately (e.g., main.wdl or main.nf)additional_files (dict of filename → file path)Register the workflow — Use CreateAHOWorkflow:
name for the workflowdefinition_source to the local ZIP path or pass the base64 output from PackageAHOWorkflowengine to WDL, NEXTFLOW, or CWLcontainer_registry_map or container_registry_map_uridescription and storage_type (default DYNAMIC)Verify registration — Use GetAHOWorkflow to confirm status is ACTIVE
Example flow:
PackageAHOWorkflow(main_file_content="./workflow/main.nf", additional_files={"modules/bwa.nf": "./workflow/modules/bwa.nf", ...})
→ CreateAHOWorkflow(name="my-pipeline", definition_source=<zip_path>, engine="NEXTFLOW")
→ GetAHOWorkflow(workflow_id=<id>) # verify ACTIVE
Help the user identify input files.
Use the HealthOmics MCP SearchGenomicsFiles tool to find FASTQ, BAM, VCF, or
reference files in configured S3 buckets.
If the RODA MCP is available, use it to find public datasets for testing:
Common test datasets:
Create a parameters file matching the workflow's parameter template:
{
"input_fastq_r1": "s3://bucket/data/sample_R1.fastq.gz",
"input_fastq_r2": "s3://bucket/data/sample_R2.fastq.gz",
"reference_fasta": "s3://bucket/references/GRCh38.fasta",
"sample_name": "NA12878",
"output_prefix": "results"
}
Use the HealthOmics MCP StartAHORun tool:
workflow_id — from the registration steprole_arn — from .healthomics/config.toml (omics_iam_role)name — descriptive name for the runoutput_uri — from .healthomics/config.toml (run_output_uri)parameters — the workflow parameters (from parameters.json)storage_type — from config (default DYNAMIC)cache_id — resolved automatically (see below)cache_behavior — from .healthomics/config.toml (CACHE_ON_FAILURE or CACHE_ALWAYS)The user should never need to remember or specify a cache ID. Resolve it automatically:
.healthomics/config.toml — if cache_id is set, use it directly.ListAHORunCaches to find existing caches:
cache_id to .healthomics/config.toml so future runs
use it without asking again.Always pass cache_id and cache_behavior when a run cache is available. During
iterative development this prevents re-running expensive tasks (like alignment or
duplicate marking) that already succeeded on a previous run.
Use the HealthOmics MCP tools for monitoring:
GetAHORun — check overall status, timing, and failure reasonsListAHORunTasks — see individual task progress and statusGetAHORunLogs — view high-level workflow execution eventsGetAHORunEngineLogs — view engine stdout/stderr for debuggingGetAHOTaskLogs — view logs for a specific taskGetAHORunManifestLogs — view workflow summary with resource metricsIf a run fails:
DiagnoseAHORunFailure to get comprehensive diagnostics including:
CreateAHOWorkflowVersionAfter successful completion:
GetAHORun to find the exact runOutputUriAnalyzeAHORunPerformanceGenerateAHORunTimeline| Symptom | Fix |
|---|---|
| "HealthOmics is not available" | Use a supported region |
| Container pull failed | Use CreatePullThroughCacheForHealthOmics to fix PTC rules |
| Access denied on S3 | Update IAM role policy with correct bucket ARN |
| Workflow stuck in CREATING | Wait up to 10 min; large workflows take time |
| Registry map mismatch | Re-register workflow after map update |
| Parameter validation error | Check workflow parameter template for name/type mismatches |
CreatePullThroughCacheForHealthOmics.LintAHOWorkflowDefinition before registration..healthomics/config.toml for saved preferences.DiagnoseAHORunFailure for failures, AnalyzeAHORunPerformance for optimization.