Hsb App

HSB Application Runner

Use this skill when the user wants to discover, select, and run Holoscan Sensor Bridge example applications on a devkit with a connected HSB board.

This skill assumes the devkit is already set up (SSH, demo container built, host configured, board connected). If setup is not complete, instruct the user to run /hsb-setup first.

This workflow runs applications inside the demo container. Only run it when the user explicitly invokes it.

Before you start — required gates (do these first, in order)

Gate 1 — Read environment variables. Before doing anything else, check these variables and print their resolved values to the user:

SSH_TARGET      Remote devkit login (e.g. nvidia@192.168.1.50). Ask the user if not set.
REMOTE_ROOT     Remote working directory (e.g. /home/nvidia). Ask the user if not set.
REMOTE_SUDO     sudo / sudo -n / "" — default to "sudo" if not set.
REMOTE_SSH_OPTS Additional SSH options (optional).
HSB_PLATFORM    Platform hint (optional).

SSH_TARGET and REMOTE_ROOT are required. Stop and ask the user for them if either is missing.

Gate 2 — Present the phase plan and get confirmation. Before taking any action:

If the user's request already includes platform, board type, and sensors, also state upfront:

• You will scan examples/ and filter apps by the user's sensor type and platform
• You will NOT add --headless automatically — only if the user explicitly requests it
• If the user specified a timeout (e.g., "60-second timeout"), state you will use that as the watchdog timeout
• Applications run inside the demo container via docker run, using python3 for Python-based examples

Show the phase plan:

HSB App — Phase Plan
  Phase 0: Verify board connectivity and demo container readiness
  Phase 1: Discover user setup and select application to run
  Phase 2: Run application with monitoring, failure analysis, and iterative debugging
  Phase 3: Generate session report (with option to save)

Then ask explicitly: Shall I proceed with Phase 0? [Y/n] — do not start Phase 0 until the user confirms.

Gate 3 — Fast path check. After the user confirms in Gate 2, run this check before executing any Phase 0 commands:

ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET \
  "grep _SESSION_VERIFIED /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || echo 'no session'"

If the output contains _SESSION_VERIFIED=true, skip Phase 0 and Phase 1 setup discovery — go directly to app selection and inform the user.

What this skill must do

1. Verify that the devkit is reachable over SSH, the HSB board is connected and responsive, and the demo container is available. Read the current FPGA version and board identity. 2. Interact with the user to understand their specific setup — repo location on the devkit, HSB software version, board type (Lattice, etc.), and connected sensors (e.g., dual IMX274, VB1940). Then scan the repository's user guide and examples/ directory to build a list of applications compatible with the user's setup. Present the list and let the user choose an app to run. 3. Run the selected application inside the demo container, monitor output, and if the app fails, analyze the log output and guide the user through debugging — including suggesting code or environment edits and re-running the app. 4. Produce a summary report of the session — issues encountered, fixes applied, and outcome. Offer to save the report to a file.

Linux/Windows-friendly wrapper variables

Reuse the same environment variables from the hsb-setup and hsb-flash skills:

• SSH_TARGET for the remote login target (e.g. nvidia@agx-thor-host)
• REMOTE_ROOT for the remote working directory
• REMOTE_SUDO for privileged commands
• REMOTE_SSH_OPTS for additional SSH options
• HSB_PLATFORM as an optional platform hint

If these are set, notify the user of these settings and use them without re-asking.

Before Phase 0, print the resolved remote execution settings.

Mandatory interaction pattern

First run in a session (no prior verification)

When no valid session state exists, show the full phase plan:

• Phase 0: Verify board connectivity and demo container readiness
• Phase 1: Discover user setup and select application to run
• Phase 2: Run application with monitoring, failure analysis, and iterative debugging
• Phase 3: Generate session report (with option to save)

Then execute one phase at a time.

Subsequent runs in the same session (fast path)

When the session state file (/tmp/.claude_hsb_app_session/state.sh) exists and contains _SESSION_VERIFIED=true, the skill skips Phase 0 and Phase 1 setup discovery because connectivity and hardware were already verified. Instead, inform the user and jump directly to app selection:

Session already verified — skipping connectivity checks.
  SSH target: $SSH_TARGET
  Board: HSB Lattice | FPGA: XXXX
  Platform: AGX Thor | HSB version: X.X.X
  Sensors: Dual IMX274

Proceeding directly to application selection.

Then execute:

• Phase 1 Steps 2–3 only (scan examples, present app list, user selects app)
• Phase 2: Run application
• Phase 3: Session report

When to re-run Phase 0 from the beginning

Phase 0 must be re-run (ignoring the fast path) when:

1. New session: No session state file exists on the remote host, or a new Claude Code session is started. 2. Execution failure suggesting connectivity loss: If Phase 2 fails with symptoms indicating the board or devkit is unreachable (ping failure, SSH timeout, container launch failure, No such device errors), clear _SESSION_VERIFIED from the session state and re-run Phase 0 before retrying. 3. User explicitly requests it: If the user says "re-verify", "start over", "run from the beginning", or invokes /hsb-app --full, run Phase 0 from scratch.

See ## Phase gate below for the full confirmation protocol.

If something fails, do not just dump raw logs. Summarize:

• the exact command that failed
• the likely root cause
• what safe action you recommend
• whether the issue is blocking

Phase details

See references/phase-details.md for full step-by-step phase instructions.

Execution rules

SSH heredoc pattern

Use the same persistent SSH session model as hsb-setup and hsb-flash. Each phase runs as a single SSH heredoc block:

ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET bash -s <<'REMOTE'
set -e

# restore state from previous phase
source /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || true
cd "${_CLAUDE_CWD:-__REMOTE_ROOT__}"

# phase commands
echo "=== Phase N: description ==="
command1
command2

# save state for next phase (preserves _SESSION_VERIFIED if already set)
_PREV_VERIFIED="${_SESSION_VERIFIED:-}"
mkdir -p /tmp/.claude_hsb_app_session
{
  echo "export _CLAUDE_CWD=\"$(pwd)\""
  echo "export PATH=\"$PATH\""
  echo "export REPO_DIR=\"$REPO_DIR\""
  echo "export VERSION=\"$VERSION\""
  echo "export HSB_PLATFORM=\"$HSB_PLATFORM\""
  echo "export BOARD_TYPE=\"$BOARD_TYPE\""
  echo "export SENSORS=\"$SENSORS\""
  echo "export FPGA_VERSION=\"$FPGA_VERSION\""
  echo "export SELECTED_APP=\"$SELECTED_APP\""
  echo "export APP_OPTIONS=\"$APP_OPTIONS\""
  echo "export APP_TIMEOUT=\"$APP_TIMEOUT\""
  [ "$_PREV_VERIFIED" = "true" ] && echo "export _SESSION_VERIFIED=true"
} > /tmp/.claude_hsb_app_session/state.sh
REMOTE

Replace __REMOTE_ROOT__ with the literal value of $REMOTE_ROOT when composing the heredoc.

Container usage for applications

Application commands run inside the demo container. Use the detached pattern with a named container.

For apps with --timeout, use the watchdog pattern. For indefinite-run apps, stream logs and wait for the user to request a stop.

Cleanup after app containers

After every app run, stop and remove the container. See references/phase-details.md for the cleanup pattern.

Session teardown

After Phase 3 (or on any failure that stops the workflow):

docker ps --filter "name=hsb_app_" --format '{{.Names}}' | xargs -r docker stop -t 2 2>/dev/null || true
ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET "rm -rf /tmp/.claude_hsb_app_session"

Phase gate — user confirmation between phases

After completing each phase (Phases 0–2), always prompt the user for confirmation before starting the next phase.

Exception: When --y (auto-approve mode) is active, phase gates are skipped. See "Auto-approve mode (--y)" section.

Proceed to Phase <N+1> (<phase description>)? [Y/n]

User response handling

All prompts in this skill require explicit typed responses. Never treat a blank or Enter-only input as a selection — re-prompt the user instead.

• "y", "yes", "Y", "ok", "go", "continue", "next" → proceed to the next phase.
• "n", "no", "stop", "abort" → stop execution. Print:

  App workflow paused after Phase N.
  You can resume by re-invoking the skill.

Then run session teardown.

• Any other text → treat as a question or instruction about the current phase. Answer it, then re-prompt.
• "retry" → re-execute the current phase, show summary again, then re-prompt.

Exceptions

• Phase 3 (session report) is the final phase — do not prompt after it unless the user wants to run another app. Show the report and offer to save.
• If a phase FAILs and cannot be recovered, stop and report clearly.

Built-in help (--help)

If $ARGUMENTS contains --help or -h, print the following and stop:

HSB Application Runner Skill

USAGE
  /hsb-app [OPTIONS]

OPTIONS
  --help, -h        Show this help message and exit
  --verbose         Show full raw command output for every phase
  --y               Auto-approve all phase gates (skip user confirmation
                    between phases). Not recommended — a confirmation
                    warning is shown before proceeding. All output is
                    saved to a timestamped log file.
  --timeout N       Set app runtime in seconds (default: no timeout,
                    app runs until user asks to stop)
  --full            Force full verification from Phase 0, even if the
                    session was already verified

ENVIRONMENT VARIABLES (set before invoking the skill)
  SSH_TARGET        Remote login target (e.g. ubuntu@10.0.0.1)
  REMOTE_ROOT       Remote working directory
  REMOTE_SUDO       Privilege escalation: 'sudo', 'sudo -n', or ''
  REMOTE_SSH_OPTS   Additional SSH options
  HSB_PLATFORM      Platform hint
  HSB_REPO_DIR      Repo directory name under REMOTE_ROOT (default: holoscan-sensor-bridge)
                    Example: HSB_REPO_DIR=hololink → repo at $REMOTE_ROOT/hololink

WORKFLOW PHASES
  Phase 0   Verify board connectivity and demo container readiness
            (skipped on repeat runs in the same session)
  Phase 1   Discover user setup, scan examples, select application
            (setup discovery skipped on repeat runs)
  Phase 2   Run application with monitoring and iterative debugging
  Phase 3   Generate and optionally save session report

EXAMPLES
  /hsb-app
  /hsb-app --verbose
  /hsb-app --timeout 60
  /hsb-app --timeout 30 --verbose
  /hsb-app --y
  /hsb-app --y --timeout 120
  /hsb-app --full
  /hsb-app --help

Invocation examples

• /hsb-app
• /hsb-app --verbose
• /hsb-app --timeout 60
• /hsb-app --timeout 30 --verbose
• /hsb-app --y
• /hsb-app --y --timeout 120
• /hsb-app --full
• /hsb-app --full --verbose
• /hsb-app --help

Verbosity mode (--verbose)

The skill supports a --verbose flag:

Detecting the flag

Check whether $ARGUMENTS (the text after the slash command) contains any of: --help / -h, --verbose, --y, --timeout N, or --full (case-insensitive). Strip all flags (and their values) from arguments before further parsing.

When --full is present, ignore any cached session state and run Phase 0 from scratch.

Verbose mode (when set)

• Show complete raw output of every SSH command
• Show full app output inline (all stdout/stderr)
• Show detailed phase status blocks

Concise mode (default, no --verbose)

• Show bullet-point summaries after each phase
• Suppress raw command output
• Show key app output lines (startup, errors, summary) but not every frame log
• Show issues with the 4-line format (Symptom, Cause, Resolution, Blocking)

Auto-approve mode (--y)

The skill supports a --y flag that skips all phase gates and runs the entire workflow from start to finish without waiting for user confirmation between phases. This is not recommended for normal use.

Confirmation warning

When --y is detected, display a warning and ask the user to confirm:

⚠  WARNING: Auto-approve mode (--y) is enabled.

This is NOT RECOMMENDED. All phase gates will be skipped and the entire
workflow will run without pausing for your confirmation between phases.

You will not be able to review intermediate results, ask questions, or
abort between phases. All output will be saved to a timestamped log file.

NOTE: In auto-approve mode, the app selection in Phase 1 will still
require your input (you must choose which app to run), but the app will
run with default settings automatically. Debug iterations in Phase 2
will be skipped — the app runs once and the result is reported.

Type 'yes' to confirm auto-approve mode, or anything else to cancel:

• If the user responds with "yes" (exact match, case-insensitive) → enable auto-approve mode.
• Any other response → cancel auto-approve mode and run interactively.

Behavior when --y is active

1. Phase gates are skipped between phases. 2. App selection still requires user input — the user must choose which app to run. 3. Default app settings are used automatically — the "defaults vs. customize" prompt is skipped and the app runs with its default options. 4. Timeout defaults to 30 seconds if no --timeout was specified on the command line (to avoid indefinite hangs). 5. Debug iterations are skipped — if the app fails in Phase 2, the failure is logged but no interactive debugging is performed. The workflow proceeds directly to the report. 6. Log file: Created at start as hsb-app-log-YYYY-MM-DD-HHMMSS.md in $REMOTE_ROOT/ or current directory. 7. Phase summaries are still shown in real time. 8. Failures still stop the workflow if they are blocking.

Combining with other flags

• --y --verbose: Auto-approve with full raw output.
• --y --timeout N: Auto-approve with a fixed app runtime.
• --y alone: Auto-approve with concise output and no timeout (app runs for a default 30 seconds in auto-approve mode to avoid indefinite hangs).

Timeout handling (--timeout)

The skill supports a --timeout N flag where N is the number of seconds to run the application.

Detecting the flag

Match --timeout followed by a whitespace-separated integer in $ARGUMENTS. Example: --timeout 60.

Behavior

• When set: The app runs for exactly N seconds, then is stopped via docker stop. The output collected during that window is shown to the user.
• When not set (interactive mode): The app runs indefinitely until the user asks to stop. The user is informed how to request a stop.
• When not set (auto-approve mode): The app runs for a default of 30 seconds to prevent indefinite hangs.

Validation

• N must be a positive integer
• Minimum: 5 seconds
• Maximum: 3600 seconds (1 hour)
• If invalid, show an error and ask the user to provide a valid timeout

Evaluation Report

Evaluation of the hsb-app skill before publication through NVSkills-Eval.

This benchmark summarizes 3-Tier Evaluation from NVSkills-Eval results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use.

Evaluation Summary

• Skill: hsb-app
• Evaluation date: 2026-05-30
• NVSkills-Eval profile: external
• Environment: local
• Dataset: 3 evaluation tasks
• Attempts per task: 2
• Pass threshold: 50%
• Overall verdict: PASS

Agents Used

• claude-code
• codex

Metrics Used

Reported benchmark dimensions:

• Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
• Correctness: checks whether the agent follows the expected workflow and produces the correct final output.
• Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
• Effectiveness: checks whether the agent performs measurably better with the skill than without it.
• Efficiency: checks whether the agent uses fewer tokens and avoids redundant work.

Underlying evaluation signals used in this run:

• security (Security): checks for unsafe operations, secret leakage, and unauthorized access.
• skill_execution (Skill Execution): verifies that the agent loaded the expected skill and workflow.
• skill_efficiency (Efficiency): checks routing quality, decoy avoidance, and redundant tool usage.
• accuracy (Accuracy): grades final-answer correctness against the reference answer.
• goal_accuracy (Goal Accuracy): checks whether the overall user task completed successfully.
• behavior_check (Behavior Check): verifies expected behavior steps, including safety expectations.
• token_efficiency (Token Efficiency): compares token usage with and without the skill.

Test Tasks

The benchmark dataset contained 3 evaluation tasks:

• Positive tasks: 3 tasks where the skill was expected to activate.
• Negative tasks: 0 tasks where no skill was expected.
• Unlabeled tasks: 0 tasks where positive/negative intent could not be inferred.

Task composition is derived from the evaluation dataset when possible. Entries with expected_skill set are treated as positive skill-activation cases, while entries with expected_skill: null are treated as negative activation cases.

Results

Score values show skill-assisted performance. Values in parentheses show uplift versus the no-skill baseline when baseline data is available.

Tier 1: Static Validation Summary

Tier 1 validation passed with observations. NVSkills-Eval ran 9 checks and found 7 total findings.

Top findings:

• MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (team-skills/holoscan/holoscan-sensor-bridge/hsb-app/SKILL.md)
• MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (team-skills/holoscan/holoscan-sensor-bridge/hsb-app/SKILL.md)
• LOW QUALITY/quality_discoverability: Description very long (267 chars, recommend 50-150) (team-skills/holoscan/holoscan-sensor-bridge/hsb-app/SKILL.md)
• LOW QUALITY/quality_discoverability: No '## Purpose' section (team-skills/holoscan/holoscan-sensor-bridge/hsb-app/SKILL.md)
• LOW QUALITY/quality_reliability: No prerequisites/requirements documented (team-skills/holoscan/holoscan-sensor-bridge/hsb-app/SKILL.md)

Tier 2: Deduplication Summary

Tier 2 validation passed. NVSkills-Eval ran 2 checks and found 0 total findings.

Notable observations:

• Context Deduplication: Collected 2 file(s)
• Inter-Skill Deduplication: Parsed skill 'hsb-app': 267 char description

Publication Recommendation

The skill is suitable to proceed toward NVSkills-Eval publication based on this benchmark. Skill owners should keep this file with the skill and refresh it when the evaluation dataset, skill behavior, or target agents materially change.

Phase Details — hsb-app

Phase 0 — Verify board connectivity and demo container readiness

Fast-path skip: If the session state file exists and contains _SESSION_VERIFIED=true, skip this entire phase. See "Subsequent runs in the same session" above.

Prerequisites

This phase assumes the devkit already has:

• A working SSH connection from the user's machine
• The HSB demo container built and available (from /hsb-setup or manual setup)
• The HSB board physically connected and powered

If any of these are missing, instruct the user to run /hsb-setup first.

Steps

1. Validate SSH connectivity to the devkit:

   ssh -o ConnectTimeout=10 -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET "echo ok"

If SSH fails, follow the same SSH key auto-remediation flow described in the hsb-setup skill.

2. Initialize the app session on the remote host:

   ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET bash -s <<'REMOTE'
   mkdir -p /tmp/.claude_hsb_app_session
   echo "export _CLAUDE_CWD=\"__REMOTE_ROOT__\"" > /tmp/.claude_hsb_app_session/state.sh
   echo "app session initialized"
   REMOTE

3. Ping the HSB board at 192.168.0.2:

   ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET "ping -c 4 -W 2 192.168.0.2"

If ping fails, inform the user and ask if the board might be at a different IP address.

4. Verify the demo container image exists:

   ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET bash -s <<'REMOTE'
   source /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || true
   cd "${_CLAUDE_CWD:-__REMOTE_ROOT__}"

   # Try to find the HSB repo and its container.
   # Honour HSB_REPO_DIR if set (e.g. "hololink"); otherwise scan common names.
   _SCAN_DIRS="${HSB_REPO_DIR:-holoscan-sensor-bridge* hololink*}"
   for dir in $_SCAN_DIRS; do
       [ -d "$dir" ] || continue
       if [ -f "$dir/VERSION" ]; then
           VERSION=$(cat "$dir/VERSION")
           if docker image inspect "hololink-demo:$VERSION" >/dev/null 2>&1; then
               echo "REPO_DIR=$dir"
               echo "VERSION=$VERSION"
               echo "CONTAINER_FOUND=yes"
               break
           fi
       fi
   done
   REMOTE

If no demo container is found, inform the user and suggest running /hsb-setup first.

5. Run `hololink enumerate` inside the demo container to read board identity:

   CONTAINER_NAME="hsb_app_enumerate_$$"
   cd $REPO_DIR
   VERSION=$(cat VERSION)
   docker run -d --name "$CONTAINER_NAME" --rm \
       --net host --gpus all --runtime=nvidia --shm-size=1gb --privileged \
       -v $PWD:$PWD -v /dev:/dev -w $PWD \
       -e NVIDIA_DRIVER_CAPABILITIES=graphics,video,compute,utility,display \
       -e NVIDIA_VISIBLE_DEVICES=all \
       hololink-demo:$VERSION \
       hololink enumerate

   ( sleep 10; docker stop -t 2 "$CONTAINER_NAME" 2>/dev/null ) &
   WATCHDOG_PID=$!
   docker logs -f "$CONTAINER_NAME" 2>&1 || true
   kill $WATCHDOG_PID 2>/dev/null
   wait $WATCHDOG_PID 2>/dev/null
   docker rm -f "$CONTAINER_NAME" 2>/dev/null || true

Parse the output to extract:

• FPGA version
• MAC address
• Serial number
• Board type — detect via `fpga_uuid`:

If the UUID matches a known value, set BOARD_TYPE to lattice or vb1940. If the UUID is not reported (older firmware) or is unknown, leave BOARD_TYPE empty — Phase 1 will ask the user.

6. Display results:

   Board and Environment:
   - SSH target: $SSH_TARGET
   - Board IP: 192.168.0.2
   - Board type: HSB Lattice / Leopard Imaging VB1940 (detected via UUID) / unknown
   - FPGA version: XXXX
   - MAC address: XX:XX:XX:XX:XX:XX
   - Demo container: hololink-demo:X.X.X (ready)

7. Mark session as verified — append the verification flag to the session state file so subsequent runs in this session can skip Phase 0:

   echo 'export _SESSION_VERIFIED=true' >> /tmp/.claude_hsb_app_session/state.sh

Phase 0 summary format

**Phase 0 — Verify board connectivity and container readiness**
- SSH connectivity to $SSH_TARGET: OK
- Board ping (192.168.0.2): 4/4 packets, 0% loss
- FPGA version: XXXX
- Board type: HSB Lattice / Leopard Imaging VB1940 (detected via UUID) / unknown
- Demo container: hololink-demo:X.X.X ready
- Status: PASS

Proceed to Phase 1 (discover setup and select application)? [Y/n]

Phase 1 — Discover user setup and select application

This phase interacts with the user to understand their hardware setup, then scans the repository to build a list of compatible applications.

Step 1 — Gather user setup details

Fast-path skip: If the session state already contains setup details (REPO_DIR, VERSION, HSB_PLATFORM, BOARD_TYPE, SENSORS), skip this step entirely. The saved setup will be used for app filtering. Show a one-line reminder of the cached setup and proceed directly to Step 2.

On a full run, ask the user for the following information. If any can be inferred from Phase 0 results or environment variables, pre-fill and confirm rather than asking from scratch:

1. HSB software repo location on the devkit: The path to the cloned holoscan-sensor-bridge repository. Default to $REMOTE_ROOT/${HSB_REPO_DIR:-holoscan-sensor-bridge} or the repo found in Phase 0. Confirm with the user.

2. HSB software version: Read from the VERSION file in the repo root. Display it and confirm.

3. Platform / devkit: Use HSB_PLATFORM if set, or ask the user:

• IGX Orin iGPU
• IGX Orin dGPU
• AGX Orin
• AGX Thor
• DGX Spark

4. Board type: Use the UUID-based detection from Phase 0 if available (BOARD_TYPE is lattice or vb1940). Confirm with the user. If Phase 0 did not detect a board type (UUID was absent or unknown), ask the user:

• HSB Lattice (CPNX100-ETH-SENSOR-BRIDGE standalone board)
• Leopard Imaging VB1940 (all-in-one Eagle Camera with integrated FPGA)

5. Connected sensors / cameras: Ask the user which sensor(s) are connected to the HSB board. Common configurations include:

• Dual IMX274 cameras
• Single IMX274 camera
• VB1940 camera (integral to VB1940 board type)
• IMX477 camera
• Other (ask user to specify)

If the user is unsure, suggest they check the physical board or refer to the user guide.

Display the collected setup summary:

Your Setup:
- Repo path: /home/work/holoscan-sensor-bridge
- HSB version: X.X.X
- Platform: AGX Thor
- Board type: HSB Lattice
- FPGA version: XXXX
- Sensors: Dual IMX274

Type 'yes' to confirm or 'no' to correct:

Step 2 — Scan the repository for compatible applications

After the user confirms their setup:

1. Read the user guide at docs/user_guide/ in the repo — particularly sections about running examples, application descriptions, and platform compatibility.

2. Scan the `examples/` directory (and any Python scripts at the repo root that are runnable demos) on the remote host:

   ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET bash -s <<'REMOTE'
   source /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || true
   cd "$REPO_DIR"

   echo "=== Examples directory listing ==="
   find examples/ -name "*.py" -o -name "*.sh" -o -name "README*" | sort

   echo "=== Top-level runnable scripts ==="
   ls -1 *.py 2>/dev/null || true

   echo "=== Example READMEs ==="
   for readme in examples/*/README* examples/*/readme*; do
       if [ -f "$readme" ]; then
           echo "--- $readme ---"
           head -30 "$readme"
           echo ""
       fi
   done
   REMOTE

3. Read each example's README or docstring to determine:

• What sensor/camera it requires
• What platform it supports
• What board type it needs
• What FPGA version is required (if any)
• What command-line arguments and options it accepts
• Brief description of what the app does

4. Filter the list based on the user's setup:

• Exclude apps that require a different sensor than what the user has
• Exclude apps that require a different platform
• Exclude apps that require a board type the user doesn't have
• Apply the Known app-specific constraints table below before showing results
• Mark apps that may work but have unverified compatibility

5. Known app-specific constraints — these constraints are authoritative and override anything in the example's README. Apply them in addition to the generic filter rules above.

HSB 100G app filter: When the user's BOARD_TYPE is lattice or vb1940, exclude every app tagged as an HSB 100G application from the list — do not even show them under "possibly compatible". If future apps are added that are HSB 100G-specific, add them to the table above.

Step 3 — Present the application list and let user choose

Display the filtered list:

Compatible Applications for Your Setup:
═══════════════════════════════════════

  [1] examples/imx274_player.py
      Camera viewer for IMX274 sensors
      Sensors: IMX274 | Platform: All | Container: Yes

  [2] examples/stereo_imx274.py
      Stereo vision with dual IMX274 cameras
      Sensors: Dual IMX274 | Platform: All | Container: Yes

  [3] examples/linux_ptp_player.py
      PTP-synchronized camera capture
      Sensors: IMX274 | Platform: All | Container: Yes

  ── Possibly compatible (unverified) ──

  [4] examples/latency_test.py
      Board latency measurement tool
      Sensors: Any | Platform: All | Container: Yes

Enter the number of the application to run, or type 'info N' for details:

When the user selects an app:

1. Show the app's full details — description, command-line options, default values, and any special requirements:

   Selected: examples/imx274_player.py
   ────────────────────────────────────
   Description: Displays live video from an IMX274 camera connected to the HSB board.

   Options:
     --headless          Run without display (useful over SSH)
     --width N           Frame width (default: 1920)
     --height N          Frame height (default: 1080)
     --fps N             Target framerate (default: 30)

   Special requirements:
     - Requires DISPLAY or --headless when user requests headless mode
     - Requires IMX274 camera on sensor port 0

   Type 'defaults' to run with default settings, or 'customize' to set options:

When `--y` is active: Skip this prompt entirely and use default settings automatically.

2. If the user chooses to customize, present each option and let them set values.

3. Ask for `--timeout`: How long to run the app:

   How long should the app run?
     - Enter a number of seconds (e.g., 30, 60, 120)
     - Type 'none' for no timeout (runs until you ask to stop)

When `--y` is active: Skip this prompt and use the --timeout value from the command line, or default to 30 seconds if no --timeout was provided.

If no timeout is set (interactive mode), inform the user:

   The app will run until you tell me to stop it.
   To stop the app, type: "stop the app" or "stop" or "quit"

Phase 1 summary format

**Phase 1 — Setup discovery and application selection**
- User setup confirmed: [platform], [board], [sensors]
- HSB version: X.X.X
- Compatible apps found: N
- Selected app: examples/xxxxx.py
- App options: [defaults / custom values]
- Timeout: [N seconds / no timeout]
- Status: PASS

Proceed to Phase 2 (run the application)? [Y/n]

Phase 2 — Run application with monitoring and debugging

This phase launches the selected application, monitors its output, handles failures, and supports iterative debugging with the user.

Step 1 — Pre-run checks

1. Ping the board to confirm it's still responsive.

2. Stop any conflicting containers that might hold shared ports:

   docker ps --filter "name=hsb_" --format '{{.Names}}' | xargs -r docker stop -t 2 2>/dev/null || true

3. Set up display for GUI apps:

   DISPLAY_NUM=$(ls /tmp/.X11-unix/ 2>/dev/null | head -1 | tr -d 'X')
   export DISPLAY=":${DISPLAY_NUM:-0}"
   xhost +local:docker 2>/dev/null || true

IMPORTANT — `--headless` rule: Never add --headless to an application command automatically. Only use --headless if the user explicitly requests it. If a DISPLAY-related error occurs, inform the user of the issue and ask whether they want to re-run with --headless — do not add it on their behalf.

Step 2 — Launch the application

Run the app inside the demo container using the detached + log pattern:

CONTAINER_NAME="hsb_app_run_$$"
cd $REPO_DIR
VERSION=$(cat VERSION)

docker run -d --name "$CONTAINER_NAME" --rm \
    --net host --gpus all --runtime=nvidia --shm-size=1gb --privileged \
    -v $PWD:$PWD -v /dev:/dev -w $PWD \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e NVIDIA_DRIVER_CAPABILITIES=graphics,video,compute,utility,display \
    -e NVIDIA_VISIBLE_DEVICES=all \
    -e DISPLAY=$DISPLAY \
    hololink-demo:$VERSION \
    python3 <app_path> <app_options>

If `--timeout` is set (N seconds):

# Watchdog: force-stop after N seconds
( sleep $TIMEOUT; docker stop -t 5 "$CONTAINER_NAME" 2>/dev/null ) &
WATCHDOG_PID=$!
docker logs -f "$CONTAINER_NAME" 2>&1
EXIT_CODE=$?
kill $WATCHDOG_PID 2>/dev/null
wait $WATCHDOG_PID 2>/dev/null
docker rm -f "$CONTAINER_NAME" 2>/dev/null || true

If no timeout (run indefinitely until user asks to stop):

# Stream logs continuously
docker logs -f "$CONTAINER_NAME" 2>&1 &
LOG_PID=$!

# Inform user how to stop
echo "App is running. Tell me to 'stop' when you want to end it."

When the user asks to stop:

docker stop -t 5 "$CONTAINER_NAME" 2>/dev/null || true
docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
kill $LOG_PID 2>/dev/null || true

Step 3 — Monitor and analyze output

While the app is running (or after it completes):

1. Stream output to the user (concise mode: show key lines; verbose mode: full output).

2. Detect success indicators: Frames rendered, data received, "pipeline started", etc.

3. Detect failure indicators: Tracebacks, ERROR, CRITICAL, segfaults, timeouts, Address already in use, No such device, etc.

Step 4 — Failure analysis and iterative debugging

If the app fails or produces errors:

1. Analyze the log output and identify the root cause. Common failure categories:

2. Present the diagnosis to the user:

   Application failed — analysis:
   ───────────────────────────────
   Error: ModuleNotFoundError: No module named 'cv2'
   Cause: OpenCV is not installed in the demo container
   Suggested fix: Run 'pip install opencv-python-headless' inside the container

   Would you like me to:
   [1] Apply the fix and re-run the app
   [2] Show the full error log
   [3] Skip and proceed to the report

3. If the user chooses to fix and re-run:

• Apply the fix (install package, edit code, change environment, etc.)
• For code edits: Show the proposed change as a diff and ask for confirmation before applying:

     Proposed code edit in examples/imx274_player.py:
     Line 42:
     -   sensor = hololink.sensors.imx274(port=0)
     +   sensor = hololink.sensors.imx274(port=0, timeout=10)

     Apply this change? Type 'yes' to apply or 'no' to skip:

• Re-run the app with the same options
• Track the fix in the issues log for the Phase 3 report

4. Connectivity-related failures trigger re-verification: If the failure analysis identifies a connectivity issue (SSH timeout, board ping failure, container launch failure, No such device when the device was previously working), clear the session verification flag and inform the user:

   This failure suggests a connectivity issue. The session verification
   will be reset. Re-running Phase 0 to check board and devkit status...

Then re-run Phase 0 from scratch. After Phase 0 passes, resume at app selection (Phase 1 Step 2).

5. Allow multiple debug iterations: The user can keep debugging and re-running until the app works or they decide to move on. Each iteration is tracked.

6. If the user wants to run a different app, loop back to app selection in Phase 1 Step 2 (fast path — skip Phase 0 and setup discovery).

Step 5 — Cleanup after app run

After the app completes (success or failure) and the user is done:

docker stop -t 5 "$CONTAINER_NAME" 2>/dev/null || true
docker rm -f "$CONTAINER_NAME" 2>/dev/null || true

Phase 2 summary format

**Phase 2 — Application execution**
- App: examples/xxxxx.py
- Run duration: X seconds / until stopped
- Result: SUCCESS / FAILURE
- Debug iterations: N
- Fixes applied: [list or "none"]
- Status: PASS / FAIL

Proceed to Phase 3 (session report)? [Y/n]

Phase 3 — Session report

1. Generate a comprehensive report covering the entire session:

   ========================================
   HSB Application Runner — Session Report
   ========================================
   Date: YYYY-MM-DD HH:MM:SS
   Operator: $USER

   Environment
   -----------
   SSH Target     : $SSH_TARGET
   Platform       : AGX Thor
   Board Type     : HSB Lattice
   FPGA Version   : XXXX
   HSB Version    : X.X.X
   Sensors        : Dual IMX274
   Demo Container : hololink-demo:X.X.X

   Application Run
   ----------------
   App            : examples/xxxxx.py
   Options        : [options used]
   Timeout        : [N seconds / no timeout]
   Duration       : X seconds
   Result         : SUCCESS / FAILURE

   Debug Iterations
   -----------------
   [If no iterations:]
   App ran successfully on first attempt.

   [If iterations:]
   Iteration 1:
     Error    : <error description>
     Cause    : <root cause>
     Fix      : <what was done>
     Outcome  : Fixed / Not fixed

   Iteration 2:
     ...

   Code Edits Applied
   -------------------
   [If no edits:]
   No code edits were made.

   [If edits:]
   1. File: examples/xxxxx.py, Line 42
      Change: Added timeout parameter to sensor init
      Reason: Default timeout too short for the board's response time

   Issues Encountered
   -------------------
   [If no issues:]
   No issues encountered during the session.

   [If issues:]
   1. <Issue title>
      Symptom    : <what happened>
      Cause      : <root cause>
      Resolution : <how it was fixed>
      Blocking   : Yes / No

   Phase Summary
   --------------
   | Phase | Name                          | Status |
   |-------|-------------------------------|--------|
   | 0     | Board connectivity & container | PASS   |
   | 1     | Setup discovery & app select  | PASS   |
   | 2     | Application execution         | PASS   |
   | 3     | Session report                | PASS   |

   Overall Status: SUCCESS
   ========================================

2. Offer to save the report:

   Type 'yes' to save this report to a file, or 'no' to skip:

If the user agrees:

• Save to $REMOTE_ROOT/hsb-app-report-YYYY-MM-DD-HHMMSS.md on the remote host
• If running locally, save to the current directory
• Confirm the saved file path

3. Ask if the user wants to run another app:

   Type 'yes' to run another application, or 'no' to finish:

If yes, loop back to Phase 1 Step 2 (app scanning and selection) using the fast path — Phase 0 and Phase 1 Step 1 are skipped because the session is already verified. If no, proceed to session teardown.

4. Session teardown:

   # Stop any remaining app containers
   docker ps --filter "name=hsb_app_" --format '{{.Names}}' | xargs -r docker stop -t 2 2>/dev/null || true

   # Clean up session state
   ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET "rm -rf /tmp/.claude_hsb_app_session"

Phase 3 summary format

**Phase 3 — Session report**
- Report generated
- Report saved: [path or "not saved"]
- Status: PASS

Description: <br>

Discover and run Holoscan Sensor Bridge example applications on a connected devkit. Filters available apps by the user's platform, HSB software version, board type, and sensors. Supports timed execution, failure analysis, code-edit suggestions, and iterative re-runs. <br>

This skill is ready for commercial/non-commercial use. <br>

Owner

NVIDIA <br>

License/Terms of Use: <br>

Apache-2.0 <br>

Use Case: <br>

Developers and engineers use this skill to discover, select, and run Holoscan Sensor Bridge example applications on devkits with connected HSB boards, including failure analysis and iterative debugging. <br>

Deployment Geography for Use: <br>

Global <br>

Known Risks and Mitigations: <br>

Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br> Mitigation: Review and scan skill before deployment. <br>

Reference(s): <br>

• Phase Details <br>
• Agent Skills Specification <br>

Skill Output: <br>

Output Type(s): [Shell commands, Configuration instructions, Analysis] <br> Output Format: [Markdown with inline bash code blocks] <br> Output Parameters: [1D] <br> Other Properties Related to Output: [None] <br>

Evaluation Agents Used: <br>

• Claude Code (claude-code) <br>
• Codex (codex) <br>

Evaluation Tasks: <br>

Evaluated against 3 internal evaluation tasks (all positive skill-activation cases, 2 attempts per task, 50% pass threshold). <br>

Evaluation Metrics Used: <br>

Reported benchmark dimensions: <br>

• Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. <br>
• Correctness: Checks whether the agent follows the expected workflow and produces the correct final output. <br>
• Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant. <br>
• Effectiveness: Checks whether the agent performs measurably better with the skill than without it. <br>
• Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work. <br>

Underlying evaluation signals used in this run: <br>

• security: Checks for unsafe operations, secret leakage, and unauthorized access. <br>
• skill_execution: Verifies that the agent loaded the expected skill and workflow. <br>
• skill_efficiency: Checks routing quality, decoy avoidance, and redundant tool usage. <br>
• accuracy: Grades final-answer correctness against the reference answer. <br>
• goal_accuracy: Checks whether the overall user task completed successfully. <br>
• behavior_check: Verifies expected behavior steps, including safety expectations. <br>
• token_efficiency: Compares token usage with and without the skill. <br>

Evaluation Results: <br>

Skill Version(s): <br>

1.0.0 (source: frontmatter) <br>

Ethical Considerations: <br>

NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>

(For Release on NVIDIA Platforms Only) <br> Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns here. <br>