/holoscan-module-lifecycle

name: holoscan-module-lifecycle
description: "Develop external Holoscan Modules with the Holoscan CLI and use them in Holoscan applications: scaffold, test, Python bindings, DEB/WHEEL packaging, and clean-consumer proof."
license: Apache-2.0
metadata:
  author: "Holoscan Team <holoscan-team@nvidia.com>"
  compatibility: "Holoscan CLI 5.x (verified with 5.0.0); Python 3.12–3.14; packaged template requires Holoscan SDK 5.0.0 or later"
  github-url: "https://github.com/nvidia-holoscan/holoscan-applications"
  tags:
    - holoscan
    - modules

Holoscan Module lifecycle

Purpose

Take a reusable Holoscan Module from layout and API contract through producer, consumer, and clean artifact-install proof. Use `uv run holoscan` in a standalone module, or `holoscan` in its activated pip environment.

A Holoscan Module extends `holoscan::core` with operators, resources, and helpers for a domain capability, plus examples and tests. Core modules ship with the SDK; external modules live in their own repositories, and applications, including those in nvidia-holoscan/holoscan-applications, consume their installed packages. This skill covers external Holoscan Module development and consumption. For SDK core-module implementation, follow the selected SDK checkout’s `modules/DEVELOPER.md` and module-specific guide; do not apply the external CLI template or packaging workflow to SDK core modules.

Inputs

Required: the API contract, workspace, identities, SDK floor, license, maintainer, package formats, and acceptance checks, from the request or an authoritative repository source. Optional: a consuming application. If consequential release metadata remains unknown, stop before scaffolding or packaging rather than guessing.

• a reusable producer/consumer API contract rather than an ordinary app;
• the user-provided standalone module repository, or the parent directory for

a new one;

• language, module/operator/package identities, minimum SDK version, license,

maintainer details, and requested package formats;

• the consuming application, if any, such as one in a holoscan-applications

checkout;

• finite producer, consumer, and artifact acceptance checks.

First honor any request for planning only (for example, “do not run commands”); preserve that restriction when routing. Check the session’s available skill catalog for the destination skill. Route a concrete failing or wrong `holoscan` command to `holoscan-app-debug-build-run`. If the matching skill is unavailable, preserve the handoff context and name the skill to install instead of broadening this workflow. An ordinary application without a reusable module API is outside this skill; follow the target repository's own guidance, such as `README.md` and `CONTRIBUTING.md` in holoscan-applications.

Prerequisites

• For module concepts and producer and consumer walkthroughs, use the

[Holoscan Modules tutorials](https://github.com/nvidia-holoscan/holoscan-tutorials/tree/main/tutorials/holoscan-modules): [create a module](https://github.com/nvidia-holoscan/holoscan-tutorials/tree/main/tutorials/holoscan-modules/create-a-module) and [use a module](https://github.com/nvidia-holoscan/holoscan-tutorials/tree/main/tutorials/holoscan-modules/use-a-module). Recheck their version-sensitive commands against the selected checkout and CLI contract. If they are unavailable, use the summary above, the bundled references, and the selected CLI’s packaged template and help; identify the unavailable tutorial and do not claim to have checked it.

• Always read the [Holoscan CLI contract](references/holoscan-cli-contract.md)

and [Holoscan CLI configuration](references/holoscan-cli-configuration.md).

• Read [module development](references/module-development.md) for layout,

naming, scaffold, metadata, implementation, build, and test scope.

• Read [consumers and packaging](references/module-consumer-packaging.md) when

a consuming app, Python binding consumer, or binary artifact is in scope.

The module's own `README.md`, `DEVELOPER.md`, and `AGENTS.md`, a consuming checkout's guidance, local help, schemas, templates, tutorials, and nearby examples are the live technical authority where they do not conflict with user, system, or safety constraints.

Instructions

For a planning-only request, return the proposed workflow and proof requirements without executing commands or changing files. Otherwise continue below.

At any step, a failing effect-bearing CLI command ends this happy path; follow Troubleshooting with its exact context. Parse read-only diagnostic results and stop only when a failed capability is required by the module, consumer, packaging environment, or requested proof. For example, a failed Docker capability blocks a container build; an unavailable display need not block an explicitly headless consumer.

1. **Preserve and orient.** Record full HEAD, concise status, selected CLI version/environment, and discovery output. Preserve the checkout revision and unrelated work. 2. **Choose the layout.** Use a standalone `holoscan-<name>` repository with its own demo applications. holoscan-applications keeps applications only and directs reusable operators and Modules to independent repositories. 3. **Fix identities before files.** Keep display name, `snake_case` module/namespace, `holoscan-<kebab-case>` repository/package, and `snake_case_op` operator slug consistent. 4. **Scaffold with the packaged template.** Follow the uv-first creation sequence in the development reference, from a parent directory outside any application checkout. Preview and run the same non-interactive `holoscan create` command with explicit language (`cpp`, or `cpp python` to add Python bindings) and agreed metadata. Always specify `--context holoscan_version=<agreed-sdk-floor>` to override configured or template defaults; the template requires 5.0.0 or later, and its preview does not check that floor. Examples explicitly