HoloHub Holoscan Module lifecycle
Purpose
Take a reusable Holoscan Module from layout and API contract through producer,
consumer, and clean artifact-install proof.
Inputs
Require the API contract, checkout, layout, identities, SDK floor, license,
maintainer, package formats, and acceptance checks from the request or an
authoritative repository source. 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 HoloHub checkout;
- external self-contained repository or in-tree descriptor layout;
- language, module/operator/package identities, minimum SDK version, license,
maintainer details, and requested package formats;
- finite producer, consumer, and artifact acceptance checks.
Route an ordinary app to holohub-app-lifecycle and a concrete failing or
wrong ./holohub command to holohub-debug-build-run. If the matching skill
is unavailable, preserve the handoff context and name the skill to install
instead of broadening this workflow.
Prerequisites
- Always read the CLI contract.
- Read module development for layout,
naming, scaffold, metadata, implementation, build, and test scope.
- Read consumer and packaging when a
consuming app, editable install, or binary artifact is in scope.
- Use HoloHub's current create-a-module
and use-a-module
tutorials as producer and consumer walkthroughs, then recheck
version-sensitive commands against the selected checkout and CLI contract.
The selected checkout's AGENTS.md, local help, module guidance, schemas,
templates, tutorials, and nearby examples are the live technical authority
where they do not conflict with user, system, or safety constraints.
Instructions
At any step, a failing effect-bearing wrapper 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.
- Preserve and orient. Record full HEAD, concise status, local wrapper
version/environment, and discovery output. Preserve the checkout revision
and unrelated work.
- Choose the layout. Use an external
holoscan-<name> repository for
independent release or an in-tree descriptor under modules/ for code
maintained with HoloHub.
- Fix identities before files. Keep display name,
snake_case
module/namespace, holoscan-<kebab-case> repository/package, and
snake_case_op operator slug consistent.
- Scaffold external modules safely. Preview template setup, inspect its
host dependency installation, and obtain explicit user authorization before
the real setup. Only after setup succeeds, preview and run the fully
specified non-interactive create command, treating preview as potentially
mutating. Require an existing parent, inspect the generated staged Git
repository, and never push it without a request.
- 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. In HoloHub, test every declared operator and demo because
test <module> is not module-scoped. In a generated repository, combine its
repository-wide test with focused pytest or CTest targets.
- Prove a real consumer. Declare the exact metadata dependency and an
immutable full SHA for external source. Use a mounted source override for
fast iteration or an editable install only in the environment reported by
env-info --json. Record the hook and remove it even if a later step fails;
if removal fails, report the exact environment and hook state.
- Package only after behavior proof. Preview and build requested DEB/WHEEL
artifacts, inspect identity/metadata/dependencies/payload, and install each
format in a clean artifact-only consumer with an import/link and finite
smoke check.
- 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 repository-required full lint in a clean
disposable checkout. Confirm no generated artifacts or editable hooks are
staged. Do not commit, push, upload, publish, or release unless requested.
Troubleshooting
If a wrapper command fails, stop the happy path and hand off its exact command,
revision, dirty state, inputs, and observed result to
holohub-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 run
sudo ./holohub; obtain approval for host packages, host-local
execution, root containers, devices/capabilities, or permission changes.
- Keep build, data, install, package output, and editable hooks 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.
1---2name: holohub-module-lifecycle3description: "Use for reusable Holoscan Module work with ./holohub: scaffold, tests, editable install, DEB/WHEEL packaging, and clean-consumer proof."4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/nvidia/holohub-module-lifecycle7 author: "Holoscan Team <holoscan-team@nvidia.com>"8 compatibility: "holoscan-cli>=4.5.0"9 github-url: "https://github.com/nvidia-holoscan/holohub"10 tags:11 - holoscan12 - holohub13 - modules14---1516# HoloHub Holoscan Module lifecycle1718## Purpose1920Take a reusable Holoscan Module from layout and API contract through producer,21consumer, and clean artifact-install proof.2223## Inputs2425Require the API contract, checkout, layout, identities, SDK floor, license,26maintainer, package formats, and acceptance checks from the request or an27authoritative repository source. If consequential release metadata remains28unknown, stop before scaffolding or packaging rather than guessing.2930- a reusable producer/consumer API contract rather than an ordinary app;31- the user-provided HoloHub checkout;32- external self-contained repository or in-tree descriptor layout;33- language, module/operator/package identities, minimum SDK version, license,34 maintainer details, and requested package formats;35- finite producer, consumer, and artifact acceptance checks.3637Route an ordinary app to `holohub-app-lifecycle` and a concrete failing or38wrong `./holohub` command to `holohub-debug-build-run`. If the matching skill39is unavailable, preserve the handoff context and name the skill to install40instead of broadening this workflow.4142## Prerequisites4344- Always read the [CLI contract](references/holohub-cli-contract.md).45- Read [module development](references/module-development.md) for layout,46 naming, scaffold, metadata, implementation, build, and test scope.47- Read [consumer and packaging](references/module-consumer-packaging.md) when a48 consuming app, editable install, or binary artifact is in scope.49- Use HoloHub's current [create-a-module](https://github.com/nvidia-holoscan/holohub/tree/main/tutorials/holoscan-modules/create-a-module)50 and [use-a-module](https://github.com/nvidia-holoscan/holohub/tree/main/tutorials/holoscan-modules/use-a-module)51 tutorials as producer and consumer walkthroughs, then recheck52 version-sensitive commands against the selected checkout and CLI contract.5354The selected checkout's `AGENTS.md`, local help, module guidance, schemas,55templates, tutorials, and nearby examples are the live technical authority56where they do not conflict with user, system, or safety constraints.5758## Instructions5960At any step, a failing effect-bearing wrapper command ends this happy path;61follow Troubleshooting with its exact context. Parse read-only diagnostic62results and stop only when a failed capability is required by the module,63consumer, packaging environment, or requested proof.64651. **Preserve and orient.** Record full HEAD, concise status, local wrapper66 version/environment, and discovery output. Preserve the checkout revision67 and unrelated work.682. **Choose the layout.** Use an external `holoscan-<name>` repository for69 independent release or an in-tree descriptor under `modules/` for code70 maintained with HoloHub.713. **Fix identities before files.** Keep display name, `snake_case`72 module/namespace, `holoscan-<kebab-case>` repository/package, and73 `snake_case_op` operator slug consistent.744. **Scaffold external modules safely.** Preview template setup, inspect its75 host dependency installation, and obtain explicit user authorization before76 the real setup. Only after setup succeeds, preview and run the fully77 specified non-interactive create command, treating preview as potentially78 mutating. Require an existing parent, inspect the generated staged Git79 repository, and never push it without a request.805. **Implement the smallest public contract.** Validate metadata, expose one81 useful operator/API, add deterministic tests, and add a finite demo that82 consumes the same public surface as another project. Keep demo policy out of83 the reusable operator.846. **Build and test honestly.** Preview and run container-first module and demo85 commands. In HoloHub, test every declared operator and demo because86 `test <module>` is not module-scoped. In a generated repository, combine its87 repository-wide test with focused pytest or CTest targets.887. **Prove a real consumer.** Declare the exact metadata dependency and an89 immutable full SHA for external source. Use a mounted source override for90 fast iteration or an editable install only in the environment reported by91 `env-info --json`. Record the hook and remove it even if a later step fails;92 if removal fails, report the exact environment and hook state.938. **Package only after behavior proof.** Preview and build requested DEB/WHEEL94 artifacts, inspect identity/metadata/dependencies/payload, and install each95 format in a clean artifact-only consumer with an import/link and finite96 smoke check.979. **Validate and hand off.** Rerun producer and clean-consumer checks,98 `git diff --check`, and final status. In a dirty checkout, restrict99 auto-fixing lint to task paths; before a requested commit, validate the100 exact candidate change with the repository-required full lint in a clean101 disposable checkout. Confirm no generated artifacts or editable hooks are102 staged. Do not commit, push, upload, publish, or release unless requested.103104## Troubleshooting105106If a wrapper command fails, stop the happy path and hand off its exact command,107revision, dirty state, inputs, and observed result to108`holohub-debug-build-run`.109110## Examples111112- Scaffold and package a reusable operator with clean-consumer proof: use this113 skill.114- Package an ordinary app or diagnose a failing build: route out of this skill.115116## Limitations117118- Preserve unrelated work. Do not reset, clean, remove unrelated files, change119 host configuration, broaden privileges, commit, push, upload, publish, or120 release without authorization.121- Never run `sudo ./holohub`; obtain approval for host packages, host-local122 execution, root containers, devices/capabilities, or permission changes.123- Keep build, data, install, package output, and editable hooks out of commits.124- Protect credentials, proprietary source, patient data, private media, and125 identifying metadata.126- Claim support, reproducibility, installability, performance, or safety only127 for the producer, artifacts, and clean-consumer evidence actually collected.128129## Output130131Return layout and identities, public API/demo, metadata and registrations,132preview and real command results, honest test scope, consumer proof, artifact133identity/contents/install results, licensing and publication limits, and final134worktree state.135136For a planning-only request, return the proposed order, authoritative metadata137sources, approval boundaries, and proof requirements without claiming results.