Holoscan Module Lifecycle
NVIDIAOfficialCreated by Holoscan TeamDistributed by NVIDIA
- Skill
- Workflow
- Software development
- Apache-2.0
- Medium risk
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
Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/holoscan-module-lifecycle/downloadUnzip 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
For module concepts and producer and consumer walkthroughs, use the Holoscan Modules tutorials: create a module and 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 and Holoscan CLI configuration.
Read module development for layout, naming, scaffold, metadata, implementation, build, and test scope.
Read consumers and packaging 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.
Preserve and orient. Record full HEAD, concise status, selected CLI version/environment, and discovery output. Preserve the checkout revision and unrelated work.
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.Fix identities before files. Keep display name,
snake_casemodule/namespace,holoscan-<kebab-case>repository/package, andsnake_case_opoperator slug consistent.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 createcommand with explicit language (cpp, orcpp pythonto 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.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.
Build and test honestly. Preview and run container-first module and demo commands, passing
--language cppor--language pythonwhen a project declares both. The module'stestruns its repository-wide suite; combine it with focused pytest or CTest targets and report the scope.Prove a real consumer. An application consumes the installed package with
find_package(holoscan-<name> CONFIG REQUIRED)andholoscan::<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 theholoscan-<name>-pythoncomponent 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 substituteinstall --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.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.tomlbuilds one. For DEB, verify the declaredholoscanDebian 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.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
holoscanwithsudo; obtain approval forholoscan 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
- ATTRIBUTION.mdAdded by AutoGineer940 B
- BENCHMARK.md8.5 KiB
- LICENSELicence file added by AutoGineer11.2 KiB
- SKILL.md10.7 KiB
- evals/evals.json13.2 KiB
- evals/extended-evals.json4.4 KiB
- references/holoscan-cli-configuration.md6.8 KiB
- references/holoscan-cli-contract.md11.1 KiB
- references/module-consumer-packaging.md9.2 KiB
- references/module-development.md6.8 KiB
- skill-card.md5.8 KiB
- skill.oms.sig5.7 KiB
evals/evals.json
[
{
"id": "holoscan-module-lifecycle-008",
"question": "Planning only: I have Python 3.12 and uv, and no project checkout. Show how to create a standalone Holoscan Module with holoscan-cli 5.0.0 for SDK 5.0.0 whose C++ operator I can also call from Python, then build, test, and package it. Do not execute or publish anything.",
"expected_skill": "holoscan-module-lifecycle",
"expected_script": null,
"ground_truth": "Use the packaged CLI Module template with Python 3.12–3.14. Prefer uvx --from holoscan-cli[create]==5.0.0 holoscan create from PyPI with --language cpp python, non-interactive mode, an explicit holoscan_version=5.0.0 context, and agreed metadata, previewed before the matching creation; the preview does not validate the SDK floor. No holoscan-applications checkout, launcher, or template setup is needed. Inspect destination/Git state and the generated pins, which route holoscan-cli to NVIDIA's index for uv run. Develop through uv run holoscan with an explicit --language for the two-language example; pip in .venv is the fallback. Package a C++-only DEB; the Python bindings install from the holoscan-<name>-python CMake component, and no wheel is generated. Preserve planning-only limits and publication authorization. Require actual functional producer and clean-consumer proof before claiming support.",
"expected_behavior": [
"Activates holoscan-module-lifecycle and preserves existing user work",
"Uses uvx with the exact holoscan-cli[create]==5.0.0 pin from PyPI and Python 3.12–3.14, documenting .venv/pip as the fallback",
"Previews packaged-template creation with --language cpp python and an explicit SDK 5.0.0 minimum before the identical action",
"Does not clone holoscan-applications, run template setup, or create a launcher for the standalone module",
"Uses uv run holoscan with explicit language selection for builds and runs, requires finite tests, and plans a DEB-only package with clean artifact-consumer proof",
"Does not invent a wheel or Python-implemented operator, execute for a planning-only request, or publish without authorization"
]
},
{
"id": "holoscan-module-lifecycle-009",
"question": "Planning only: an application in my holoscan-applications checkout should use the C++ operator from my standalone module, holoscan-my-module. I added the module to application.dependencies.modules[] with its git URL and an immutable SHA, and I also want to try an uncommitted local working tree of the module. What sequence proves the consumer? Do not execute anything.",
"expected_skill": "holoscan-module-lifecycle",
"expected_script": null,
"ground_truth": "The agent activates the module lifecycle and explains that in holoscan-applications neither the metadata dependency nor a HOLOSCAN_CLI_LOCAL_HOLOSCAN_MY_MODULE override fetches or builds the module: the CLI writes external_operators_manifest.cmake, but the repository's root CMakeLists.txt does not include it, and changing the shared root CMake needs maintainer agreement. It plans to build the module from the local working tree, install its C++ component from the exact build directory into a fresh task-owned prefix built against the same SDK and image family, have the application's own CMake call find_package(holoscan-my-module CONFIG REQUIRED) and link holoscan::my_module, then mount the prefix with --add-volume and pass -Dholoscan-my-module_DIR with the container path through --configure-args. It previews the identical holoscan run command, notes that dry runs hide CMake option values, requires configure evidence that the package resolved from the mounted prefix plus a finite consumer result, and removes the prefix with verified cleanup. It executes nothing.",
"expected_behavior": [
"Activates holoscan-module-lifecycle and explains that the metadata dependency and local override do not build the module in holoscan-applications because its root CMake does not include the CLI manifest",
"Does not add FetchContent or modify the shared root CMake without maintainer agreement",
"Installs the module from the exact build directory into a fresh task-owned prefix and consumes it with find_package and the holoscan::my_module target",
"Mounts the prefix with --add-volume and passes the container-side package directory through --configure-args",
"Previews the identical run command, requires configure evidence of the mounted package and a finite consumer result, and plans verified prefix cleanup",
"Does not execute, fetch, commit, or publish anything"
]
},
{
"id": "holoscan-module-lifecycle-006",
"question": "Planning only: `uv run holoscan package` fails on my standalone module partway through CMake. Explain how you would reproduce it and make the smallest fix. Do not execute commands or modify files.",
"expected_skill": null,
"expected_script": null,
"ground_truth": "The module-lifecycle skill stays silent because one exact command fails. The agent should route to holoscan-app-debug-build-run, preserve and preview the command, isolate the first causal layer, and describe how it would prove a minimal fix without executing anything.",
"expected_behavior": [
"Does not activate holoscan-module-lifecycle's happy path",
"Routes to holoscan-app-debug-build-run",
"Preserves the exact failing command, full revision, dirty state, and meaningful inputs",
"Does not execute commands or modify files, and avoids speculative cache deletion, broad dependency upgrades, or publishing"
]
},
{
"id": "holoscan-module-lifecycle-005",
"question": "My standalone module, created by holoscan-cli 5.0.0 with --language cpp python, builds and its tests pass. Package it as a Debian package and a wheel with `uv run holoscan package`, confirm both work for clean consumers, and do not publish.",
"expected_skill": "holoscan-module-lifecycle",
"expected_script": null,
"ground_truth": "The agent validates module metadata and recognizes that the packaged template produces a C++-only DEB that excludes the Python bindings and builds no wheel, so WHEEL is unavailable unless the module's own pyproject.toml builds one; it does not invent wheel packaging and reports that format as unsupported for this module. It previews and runs DEB packaging container-first, records the actual artifact path, inspects dpkg-deb --info and --contents against metadata, installs the DEB in a disposable artifact-only consumer whose package database provides the declared holoscan dependency, and proves a link or import plus a finite smoke result; for Python consumers it uses the holoscan-<name>-python CMake component instead. It does not publish.",
"expected_behavior": [
"Activates holoscan-module-lifecycle and confirms module metadata, namespace, version, and dependencies",
"Recognizes that the packaged template produces a C++-only DEB and no wheel, and does not invent wheel packaging",
"Previews explicit uv run holoscan package commands with --dryrun --verbose before the matching action and records actual artifact paths",
"Inspects Debian control and payload rather than trusting exit zero, and checks the declared holoscan dependency in the consumer",
"Proves the DEB from a clean consumer that cannot import or link from the checkout, build tree, user site, or local override",
"Does not commit, push, upload, publish, or remove unrelated files without authorization"
]
},
{
"id": "holoscan-module-lifecycle-010",
"question": "Planning only: my standalone module is open at src/operators and I want SDK 5.x from a local install, a shared CUDA setting, and a sensor configuration file visible inside Docker. The CLI is 5.0.0. What should I configure?",
"expected_skill": "holoscan-module-lifecycle",
"expected_script": null,
"ground_truth": "Use root discovery or a global --project-root before the command, [tool.holoscan] for the shared cuda setting and forward-env names, a separate mount for the sensor file, and --local-sdk-root or HOLOSCAN_SDK_ROOT for the SDK; otherwise the CLI picks a default SDK location without checking the module's minimum version. Preview effective sources with --dryrun --verbose. Do not infer SDK 5 compatibility from CLI 5; SDK 5 uses CUDA 13, Python bindings need the SDK's Python package, and actual tests are required. No launcher duplication or secrets in TOML.",
"expected_behavior": [
"Uses discovered or explicit global project root without copying a launcher",
"Separates environment names from values and filesystem mounts",
"Selects the SDK explicitly, distinguishes CLI version from SDK support, and keeps native/container artifacts separate",
"Proposes effective configuration previews and real compatibility proof without executing"
]
},
{
"id": "holoscan-module-lifecycle-011",
"question": "Planning only: my module was generated by CLI 5.0.0a1 and still pins holoscan-cli==5.0.0a1. uv chooses Python 3.14 and dependency resolution fails. Should I relax the CLI pin or add uv python pin 3.12 to every project?",
"expected_skill": "holoscan-module-lifecycle",
"expected_script": null,
"ground_truth": "The published 5.0.0a1 wheel excludes Python 3.14+, while the 5.0.0 wheel declares <3.15; a newer release does not update the alpha artifact or the module's pin. Keep the requested CLI pin and select Python 3.12 or 3.13 for this environment, for example uv run --python 3.12 holoscan version --json, or with authorization move the module's requirements, development-group, and pre-commit CLI pins together. Do not impose a repository-wide Python pin, bypass Requires-Python, or downgrade below the workflow Python 3.12 floor. Verify interpreter/version before further commands, respecting planning-only scope.",
"expected_behavior": [
"Identifies the alpha upper bound and workflow minimum separately",
"Preserves the CLI pin and selects a compatible interpreter only where needed",
"Does not edit project configuration, install into system Python, or execute during planning"
]
},
{
"id": "holoscan-module-lifecycle-012",
"question": "My module generated by CLI 5.0.0 builds a DEB, but dpkg -i in my SDK 5.0.0 development container says Package holoscan is not installed. The C++ example builds and runs there. Can I force installation and claim clean-consumer support? Planning only.",
"expected_skill": "holoscan-module-lifecycle",
"expected_script": null,
"ground_truth": "The module lifecycle covers clean-consumer DEB verification. The agent distinguishes a working SDK build environment from Debian package registration: the DEB declares holoscan (>= the minimum SDK version), which this container's package database does not provide. It compares dpkg-deb --info with dpkg-query in the consumer, uses a consumer with the real declared SDK Debian package, or reports DEB installation unverified. It does not force dependencies, synthesize a provider package, or claim clean-consumer support. Respect planning-only scope.",
"expected_behavior": [
"Activates holoscan-module-lifecycle for clean-consumer DEB verification",
"Separates a working SDK build environment from Debian dependency satisfaction",
"Inspects the DEB's declared holoscan dependency against the consumer's package database",
"Requires the actual declared dependency or reports DEB installation unverified, without forcing dependencies or fabricating provider packages",
"Does not execute commands during planning"
]
},
{
"id": "holoscan-module-lifecycle-013",
"question": "Plan a Python consumer proof for a standalone module generated by CLI 5.0.0 with --language cpp python, using an installed copy of its bindings rather than the build tree. The consumer may fail after installation, and the debugging skill may not be installed. Explain what to record, how to scope and verify cleanup, and the outcome if cleanup fails. Do not run commands or edit files.",
"expected_skill": "holoscan-module-lifecycle",
"expected_script": null,
"ground_truth": "Build first, then install only the holoscan-<name>-python CMake component from the exact build directory into a fresh task-owned prefix; do not use install --dev, because this template stages no editable-import hooks. Record the interpreter, build directory, prefix, and installed paths before the consumer runs, and confirm the prefix is new and not shared. Use guaranteed cleanup that removes only that prefix even on consumer failure, and require a zero exit status and absence of the prefix. If cleanup fails, stop using the environment and report incomplete cleanup even without the debugging skill. Do not package or claim restoration. Keep the response planning-only.",
"expected_behavior": [
"Installs only the holoscan-<name>-python component from the exact build directory into a fresh task-owned prefix and records the interpreter, prefix, and installed paths",
"Does not rely on install --dev or editable hooks for this template",
"Runs scoped cleanup of only that prefix after a failed consumer and checks both exit status and absence",
"Stops and reports incomplete cleanup if removal fails and no debug skill is available",
"Does not execute commands, edit files, or claim cleanup success"
]
}
]
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