nf-core Module Conventions

Structured digest of the nf-core module specification — the conventions a module MUST or SHOULD follow to pass nf-core modules lint. Operational grounding for two Molds:

• summarize-nextflow — when extracting tools/containers/IO from a real nf-core module, the conventions tell the cast skill what to expect and what to flag as drift.
• author-galaxy-tool-wrapper — when translating an nf-core module into a Galaxy UDT, the conventions are the contract the source-side has already enforced (versions are emitted, args go through task.ext.args, containers carry both branches, etc.).

Companion structured form: component-nf-core-module-conventions.yml. Per-rule entries with id, level, description, lint_check, evidence, affects. Cast skill consumes the YAML for confidence-checking and warning suppression.

Rule levels

• MUST — module fails lint if violated. The cast skill can assume these hold for a lint-clean module; surface a warning if not.
• SHOULD — lint warns but does not fail. The cast skill should not assume these; treat as a hint, not a contract.

Categories

The YAML groups rules into:

1. Layout — directory structure, file inventory.
2. Containers and conda — directive form, environment.yml shape (also covered structurally in component-nextflow-containers-and-envs).
3. Process and IO — input/output channel declarations, meta map keys, args via task.ext.args.
4. Versions — how each tool emits its version, the topic: versions convention.
5. Stubs and tests — mandatory stub block, nf-test presence.
6. Documentation — meta.yml fields, descriptions, keywords.
7. Code hygiene — no System.exit, no leftover Jinja, no merge markers, no TODOs in committed code.

Source provenance

Each rule’s lint_check field names the lint test inside nf-core/tools that enforces it (e.g., main_nf, meta_yml, environment_yml, module_changes, module_tests). The rule fires when the lint test reports a fail or a warn. The lint suite registry is nf_core/modules/lint/__init__.py’s lint_tests list; individual tests live in nf_core/modules/lint/<name>.py.

The evidence field cites either a specific lint-test source path or the documented spec page. When neither is precise (e.g., “convention emerges from the module template”), evidence cites the template file.

Cross-references

• component-nf-core-tools — wider tool ecosystem (modules.json, the install/update flow).
• component-nextflow-containers-and-envs — container and conda directive deep-dive (the “containers and conda” category here is the policy layer; the other note is the URL grammar).
• nf-core-module-meta — the JSON Schema this convention list operationalizes.

Open gaps

Updated when a real module exposes a convention not captured here. Each entry names the motivating module.