Implementing New Modules
Developmentimplementing-new-modulesImplementing New Modules is an Agent Skill for development published in the MultiQC/MultiQC repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Create a new MultiQC module from scratch. Parse a bioinformatics tool's output, register search patterns and entry points, add general stats columns, build plots and sections, write tests, open a PR. Use when implementing a `module: new` GitHub issue, when the user asks to add support for a new tool, or when adding a parser for a new tool output format.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/MultiQC/MultiQC/blob/HEAD/.claude/skills/implementing-new-modules/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/implementing-new-modules, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Implement New MultiQC Module
Workflow
- Research the tool: read its docs, get example output files (check
MultiQC/test-data/data/modules/first), find similar existing modules for reference. Note version- and flag-dependent output variations. - Pick architecture: single-tool or multi-subtool (see below).
- Build the module: parser, general stats, sections, plots. Full step-by-step in implementation-checklist.md.
- Register: add to
search_patterns.yamlandpyproject.tomlentry points. - Test: unit tests for parsers, integration test via
pytest tests/test_modules_run.py -k "toolname" -v, andmultiqc … --stricton test data. - Quality gate:
prek run,ruff check,python .github/workflows/code_checks.py,mypy. - PR: brief summary,
<details>for the full write-up,Closes #XXXX.
Architecture decision
Single-tool (FastQC, Qualimap): one output format, one parser.
multiqc/modules/toolname/
├── __init__.py
└── toolname.py
Multi-subtool (samtools, seqkit, picard): distinct subcommands with different output formats, or more subcommands likely to be added.
multiqc/modules/toolname/
├── __init__.py
├── toolname.py # Orchestrator
├── subtool1.py # parse_toolname_subtool1() function
├── subtool2.py # parse_toolname_subtool2() function
└── tests/
Class skeletons and full file templates: module-structure.md. Patterns for code inside a module (parsing, plots, alerts, etc.): code-patterns.md.
Common Pitfalls
- Forgetting
add_software_version()— required by linting, even if version isNone. - Calling
write_data_file()too early — must be at end, after all sections. - Raising
UserWarninginstead ofModuleNoSamplesFound. - Not handling both tab- and space-separated output when both are valid.
- Hardcoding values instead of using
f["s_name"]and other dynamic variables. - Manually cleaning sample names instead of
self.clean_s_name(). - Inappropriate colour scales — e.g.
RdYlGnfor GC% (which is not "higher is better"). - Silently defaulting on known fields —
parsed.get(key, 0)for fields the tool always emits (ortry/except: return {}over the whole parse) hides real format breakage behind a fake-looking report. Access documented keys directly; reserve.get(default)for genuinely optional fields. Catching a parse error to raise a friendlier message is fine; silently producing zeros is not. - Trivial single-statement helpers — a helper that wraps one or two lines, or just renames a one-liner, adds indirection without aiding readability. Per-section / per-parser helpers (
_add_adapter_section,_parse_log) are fine and often clearer; one-liner wrappers (_add_filtered_sectioncallingadd_sectionwith no real logic) are not. - Using raw parsed dict keys in user-facing text —
total_countsandpct_dupbelong in code, never in plot/column titles, axis labels, or section names. Convert to"Total Counts","% Duplicates". - Dropping the whole section when all samples are zero — keep the section, pass
plot=None, and add aSectionAlertvia thealerts=parameter onadd_section()listing affected samples. Don't append raw<div class="alert ...">HTML todescription— use thealertsAPI. - Pre-filtering samples at parse time — keep every sample in the main data dict so
write_data_fileis complete; filter at plot-render time. - Em-dashes (—) in any user-facing text — descriptions, docstrings, alerts, PR text. AI tell. Use commas or split sentences.