AutoGineer
Generated banner for Holoscan Module Lifecycle
Generated logo for Holoscan Module Lifecycle

Holoscan Module Lifecycle

NVIDIAOfficialCreated by Holoscan TeamDistributed by NVIDIA

  • Skill
  • Workflow
  • Software development
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

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.
— the description by Holoscan Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured workflow for developing external Holoscan Modules, which extend the Holoscan SDK with custom operators and resources. It covers the entire lifecycle from scaffolding a new module repository using the Holoscan CLI template to implementing public APIs, running tests, and packaging the module as DEB or WHEEL artifacts. The process emphasizes maintaining consistent identities, validating metadata, and proving consumer compatibility through clean-room installation checks.

What it does

  • Scaffolds new standalone Holoscan Module repositories using the official CLI template.
  • Configures module metadata, identities, and SDK version requirements.
  • Implements and validates public operator APIs and deterministic tests.
  • Builds and tests modules within containerized environments.
  • Packages modules into DEB or WHEEL formats for distribution.
  • Verifies module installability and consumer compatibility in clean environments.

When to use it

  • When creating a new reusable Holoscan Module outside of the core SDK.
  • When adding Python bindings to an existing C++ Holoscan Module.
  • When preparing a module for distribution via DEB or WHEEL packages.
  • When verifying that a consuming application can correctly link against a custom module.

Advantages

  • Ensures consistency across module development through standardized CLI scaffolding.
  • Promotes clean-room testing to verify package installability and dependency resolution.
  • Separates reusable module logic from specific application implementations.
  • Provides a clear path for integrating Python bindings with C++ Holoscan operators.

Usage examples

“Scaffold a new Holoscan module named 'image-processor' with C++ and Python support targeting SDK 5.0.0.”
The agent will initialize a new repository, configure the metadata with the specified SDK floor, and generate the necessary project structure for C++ and Python bindings.
“Package my existing Holoscan module as a DEB file and verify it in a clean environment.”
The agent will build the DEB artifact, simulate an installation in a fresh environment, and perform a smoke test to ensure the module is correctly linked and importable.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/nvidia/holoscan-module-lifecycle/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip holoscan-module-lifecycle.zip -d .agents/skills

Documentation by Holoscan Team

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

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 select 5.0.0; use the agreed SDK floor for the actual module. No launcher or holoscan-applications checkout is required. Preserve existing Git state; reject populated destinations. Inspect generated files and Git status before continuing.

  5. Implement the smallest public contract. Validate metadata, expose one useful operator/API, add deterministic tests, and add a finite demo that consumes the same public surface as another project. Keep demo policy out of the reusable operator.

  6. Build and test honestly. Preview and run container-first module and demo commands, passing --language cpp or --language python when a project declares both. The module's test runs its repository-wide suite; combine it with focused pytest or CTest targets and report the scope.

  7. Prove a real consumer. An application consumes the installed package with find_package(holoscan-<name> CONFIG REQUIRED) and holoscan::<module_slug>. In holoscan-applications, a metadata dependency alone neither fetches nor builds the module; follow the application consumer procedure and do not change the shared root CMake without maintainer agreement. For Python bindings, import from the exact build tree or install the holoscan-<name>-python component into a task-owned prefix; follow the Python consumer cleanup procedure: record the interpreter, build directory, prefix, and installed paths, always remove the task-owned prefix after the consumer attempt, and verify it is absent. The packaged template stages no editable-import hooks, so do not substitute install --dev. If cleanup fails, stop using that environment and report incomplete cleanup; a missing debugging skill does not permit continuing to package or publish. Discard a task-owned disposable environment only under existing cleanup authorization; a shared environment needs the owner’s repair decision.

  8. Package only after behavior proof. Preview and build the requested artifacts, inspect identity/metadata/dependencies/payload, and install each format in a clean artifact-only consumer with an import/link and finite smoke check. The packaged template produces a C++-only DEB and no wheel; request WHEEL only for a module whose own pyproject.toml builds one. For DEB, verify the declared holoscan Debian dependency in the consumer’s package database: a successful Python import or C++ build is insufficient. If it is absent, report DEB installation unverified and follow the DEB prerequisite guidance; do not force dependency checks or claim archive extraction proves installability.

  9. Validate and hand off. Rerun producer and clean-consumer checks, git diff --check, and final status. In a dirty checkout, restrict auto-fixing lint to task paths; before a requested commit, validate the exact candidate change with the full lint required by that repository's guidance, in a clean disposable checkout. If the required commands cannot be determined, report lint unverified. Confirm no generated artifacts or install prefixes are staged. Do not commit, push, upload, publish, or release unless requested.

Troubleshooting

If a CLI command fails, stop the happy path and hand off its exact command, revision, dirty state, inputs, and observed result to holoscan-app-debug-build-run.

Examples

  • Scaffold and package a reusable operator with clean-consumer proof: use this skill.

  • Package an ordinary app or diagnose a failing build: route out of this skill.

Limitations

  • Preserve unrelated work. Do not reset, clean, remove unrelated files, change host configuration, broaden privileges, commit, push, upload, publish, or release without authorization.

  • Never prefix holoscan with sudo; obtain approval for holoscan setup, host packages, host-local execution, root containers, devices/capabilities, or permission changes.

  • Keep build, data, install prefixes, and package output out of commits.

  • Protect credentials, proprietary source, patient data, private media, and identifying metadata.

  • Claim support, reproducibility, installability, performance, or safety only for the producer, artifacts, and clean-consumer evidence actually collected.

Output

Return layout and identities, public API/demo, metadata and registrations, preview and real command results, honest test scope, consumer proof, artifact identity/contents/install results, licensing and publication limits, and final worktree state.

For a planning-only request, return the proposed order, authoritative metadata sources, approval boundaries, and proof requirements without claiming results.

Files

references/module-consumer-packaging.md

Module consumers and packaging

Use uv run holoscan in a standalone module (or holoscan in an activated pip environment). A consuming application uses the module's installed package; in holoscan-applications, run holoscan from that checkout's root.

Declare the dependency

A module declares dependencies under module.dependencies[], and an application can declare modules under application.dependencies.modules[]. Each entry names the dependency exactly as the producer's metadata.json:module.name, declares provides_operators, and, for external source, supplies source.git_url plus an immutable 40-character commit SHA in source.ref; tags and branches are rejected. The CLI parses these entries on every build and run, including dry runs, and fails on one without that source, while metadata schema validation does not check them. Validate against current schemas and real targets. A CMake consumer of an installed module uses find_package(holoscan-<name> CONFIG REQUIRED) and links the aggregate holoscan::<module_slug> target or an individual operator target.

During build and run, the CLI turns declared source dependencies into external_operators_manifest.cmake in the build directory and honors a HOLOSCAN_CLI_LOCAL_<SANITIZED_MODULE_NAME> source override there. Derive the key from the dependency's name: replace non-alphanumeric runs with _, trim leading/trailing underscores, and uppercase, so holoscan-my-module becomes HOLOSCAN_CLI_LOCAL_HOLOSCAN_MY_MODULE. Only a consuming root CMakeLists.txt that includes that manifest fetches and builds the module.

Consume from an application in holoscan-applications

holoscan-applications' root CMakeLists.txt does not include the manifest, so neither a declared dependency nor a local override fetches or builds the module there. Do not add FetchContent or change the shared root CMake without maintainer agreement. Prove consumption from an installed package built against the same SDK and image family as the application:

  1. Create an empty task-owned prefix directory and install the module's default (C++) component into it from the exact producer build directory, in the environment that produced the build. A --local build installs on the host. A default container build records container paths, so install it inside the module's development container with the prefix mounted, after previewing the launch:

    uv run holoscan run-container --add-volume <task-owned-prefix> --dryrun --verbose -- \
  'cmake --install <container-build-dir> --prefix /workspace/volumes/<prefix-name>'

    Alternatively, install the module's DEB in a disposable consumer image with approval.

  2. In the application's own CMake, call find_package(holoscan-<name> CONFIG REQUIRED) and link holoscan::<module_slug> or an operator target. Record the dependency in the application's README, and in its metadata only as a complete source entry.

  3. Point configure at the package without replacing the CLI's SDK prefix. In container mode, mount the prefix and pass its container path; keep preview and action identical except for --dryrun:

    holoscan run <consumer-app> <mode> --language cpp \
  --add-volume <task-owned-prefix> \
  --configure-args='-Dholoscan-<name>_DIR=/workspace/volumes/<prefix-name>/lib/cmake/holoscan-<name>' \
  --dryrun --verbose

    Dry runs hide CMake option values. In the real run, confirm from configure output that the package resolved from the mounted prefix, then require a finite consumer result.

  4. Remove the task-owned prefix afterwards with the guaranteed cleanup below.

Python bindings consumer

A module created with --language cpp python exposes its C++ operators to Python as holoscan_<snake_name>. The packaged template stages no editable-import hooks: install --dev installs only hooks that a build staged as holoscan_<snake_name>_dev.py, so for this template its preview can announce an install that the real action rejects. Do not use it here.

Build first, then prove Python consumption in one of two ways:

  • from the build tree, with only that build's python/lib directory and the SDK's Python paths on PYTHONPATH; or

  • from the holoscan-<name>-python CMake component installed into a fresh task-owned prefix:

cmake --install <exact-build-dir> --component holoscan-<name>-python --prefix <task-owned-prefix>

The component is excluded from the default install and from the DEB. Run the install in the environment that produced the build, as for the C++ component above. Before installing, record the interpreter executable, the exact build directory, and the prefix; confirm the prefix is absent or empty and is not shared with other work. Record the installed paths that cmake --install reports.

Use a finally block or equivalent guaranteed cleanup path around the consumer attempt. Remove only the task-owned prefix, even if the consumer failed. Cleanup succeeds only when removal returns zero and the prefix no longer exists; verify this with Path.exists() or an equivalent filesystem check. A successful removal of a different path is not proof.

On a removal failure or a remaining prefix, stop consumer/package work and report the interpreter, prefix and its state, and the error in a redacted local handoff. Do not add privileges or delete unrelated files. Route the failure to holoscan-app-debug-build-run if available. If it is unavailable, end with cleanup incomplete and the affected environment unsuitable for further validation; do not claim restoration. A task-owned disposable environment can be discarded under the existing cleanup authorization, but a shared environment requires the owner's repair decision.

Package and inspect

Package only after producer and consumer behavior is proved:

uv run holoscan package <module> --pkg-generator DEB --dryrun --verbose
uv run holoscan package <module> --pkg-generator DEB --verbose

The packaged template produces only a DEB. It contains the C++ operators, installs under /usr when built against SDK 5, declares holoscan (>= <minimum-sdk-version>), and excludes the Python bindings; the template builds no wheel. A module whose own pyproject.toml builds a wheel can request --pkg-generator DEB,WHEEL; WHEEL also needs the Python build package.

With holoscan-cli 5.0.0, the package dry run does not create package directories. It also honors the explicit <module> argument; a real package action fails when that module produces no CPack configuration. Record actual artifact paths from the action. Inspect wheel file lists and *.dist-info/METADATA; compare name, version, dependencies, and namespace with module metadata. Inspect dpkg-deb --info and --contents; compare package identity, dependencies, and payload paths.

Clean consumer proof

Install every requested format in a separate disposable consumer inside a SDK-equipped test environment. Import/link the declared namespace and run a finite demo or minimal smoke. If platform, policy, dependency, or privilege prevents this, mark that format unverified; package exit zero is insufficient. Installing a DEB changes the package database; obtain approval before doing so outside a disposable consumer.

For DEB, first inspect dpkg-deb --info and check each dependency with dpkg-query in the clean consumer. The 5.0.0 template declares holoscan (>= <minimum-sdk-version>), the Debian alias of holoscan-cuda-13 on SDK 5.0 platforms. An SDK container or Python wheel can provide working Holoscan libraries without registering that Debian package; SDK 4.6.0's CUDA 13 image exhibits this distinction. dpkg -i then leaves the module unconfigured. Use a consumer with the actual declared SDK Debian dependency installed, or report DEB installation unverified. Do not force dependencies, fabricate a provider package, or equate archive extraction with a successful package installation.

Prefer an artifact-only environment. For a subprocess-based consumer, use a neutral working directory such as /tmp and a process-local environment with user-site packages disabled and only documented SDK paths on PYTHONPATH. Producer checkout/build paths and local-module overrides must be absent from that subprocess environment. Keep the parent environment, skill files, and repository configuration unchanged. Record the imported module's resolved file: it must belong to the fresh artifact, not the producer checkout, /workspace, or a build tree.

Reconcile binary_packages.install_commands with what worked. Do not upload to PyPI, Debian repositories, releases, or registries without authorization and a redistribution review.

Review validation

Rerun focused producer tests and clean consumer smoke. Run git diff --check, inspect the complete diff/status, and ensure packages, install prefixes, and build trees are not staged.

Use each repository's own lint workflow: the generated module's guidance, and holoscan lint plus DCO sign-off for a consumer in holoscan-applications. In a dirty checkout, scope auto-fixing lint to task paths and validate an exact requested commit with the required full lint in a clean disposable checkout. Preview supported lint commands, inspect auto-fixes, and do not commit, push, publish, or release unless requested.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs
  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Holoscan Team
Publisher
NVIDIA (Official)
Distributed by
NVIDIA
Source
NVIDIA/skills · skills/holoscan-module-lifecycle · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Holoscan Team or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download holoscan-module-lifecycle.zip