Setting Up an Agent Skill#

Overview#

A coding agent can manage AI Workbench projects through the CLI binary.

The agent calls ~/.nvwb/bin/nvwb-cli with -c, -p, and -o json the same way a script does. See Using the CLI Binary for Scripts and Agents for the calling convention, JSON response shapes, and state machine.

The agent needs a skill definition that encodes what it should know about the CLI.

A skill is a structured prompt or tool definition that tells the agent how to call the binary, what flags to pass, and how to interpret responses.

The skill replaces documentation the agent would otherwise have to discover on its own.

The agent should run inside a sandbox.

AI Workbench provides sandboxing for agents that run inside a project container. See Sandboxing Agents with AI Workbench for how to configure the sandbox and what it restricts.

Key Concepts#

Skill definition: A file or prompt that gives the agent the calling convention, flag rules, JSON shapes, and state machine in a format it can act on directly.
State-aware execution: The agent must check project state before issuing commands that have preconditions. For example, start fails if the project has not been built, and environment variable changes fail if the container is running.
Build assistant: AI Workbench includes a build assistant that can analyze and fix failed container builds. An agent can start, stop, and check the status of the build assistant through nvwb internal build-assistant commands. See Build Assistant for the full command set.

What the Skill Should Include#

The binary path and calling convention.: The agent needs to know it calls ~/.nvwb/bin/nvwb-cli, not the nvwb wrapper. It also needs to know which flags each command requires. Commands that operate on a project need -c and -p. Commands that operate on a location need -c only. Commands that operate on AI Workbench itself need neither.
The JSON response shapes.: The agent needs to know the four response shapes (list, status, create/clone, error) so it can parse output and detect failures.
The state machine and preconditions.: The agent needs to check status before running commands like build, start, or create environment-variable, and understand which states allow which operations.
The project path rule.: The agent should always use the absolute project path with -p, not the registered project name. The name comes from spec.yaml and may not match the directory name.

Example: End-to-End Agent Workflow#

This example shows the sequence an agent follows to clone, build, configure, and start a project.

# NVWB CLI Project Setup

> **What:** Clone, build, configure, and start NVIDIA Workbench projects using `nvwb-cli`.
>
> **When to use:** Workbench project setup, cloning projects, building containers,
> setting environment variables, or launching applications.

## Prerequisites

- `nvwb-cli` installed at `$HOME/.nvwb/bin/nvwb-cli`
- A running Workbench context (typically `local`)
- `jq` available on PATH

## Setup Variables

```bash
NVWB="$HOME/.nvwb/bin/nvwb-cli"
CONTEXT="local"
PROJECT="/home/workbench/nvidia-workbench/my-project"
```

## Steps

### 1. Clone from a remote repository

```bash
$NVWB clone project https://github.com/org/repo \
--projectPath "$PROJECT" -c "$CONTEXT"
```

### 2. Check build state

```bash
BUILD_STATE=$($NVWB status -c "$CONTEXT" -p "$PROJECT" -o json \
| jq -r '.result.Environment.BuildState')
```

### 3. Build if needed

```bash
if [ "$BUILD_STATE" = "NO_BUILD" ] || [ "$BUILD_STATE" = "BUILD_ERROR" ]; then
$NVWB build -c "$CONTEXT" -p "$PROJECT"
fi
```

### 4. Set a sensitive environment variable

```bash
echo "$API_KEY" | $NVWB create environment-variable API_KEY - \
--is-sensitive -c "$CONTEXT" -p "$PROJECT"
```

### 5. Start the first application

```bash
APP_NAME=$($NVWB status -c "$CONTEXT" -p "$PROJECT" -o json \
| jq -r '.result.Applications[0].name')

$NVWB start "$APP_NAME" -c "$CONTEXT" -p "$PROJECT" --no-browser
```

After each step, the agent should check for errors.

Every error returns {"error": "...", "detail": "..."}. The agent can parse this shape consistently across all commands.

Example: Using the Build Assistant#

If a build fails, the agent can use the build assistant to diagnose and fix the issue.

# NVWB CLI Build Assistant

> **What:** Diagnose and recover from failed container builds using the `nvwb-cli` build assistant.
>
> **When to use:** Workbench build failures, `BUILD_ERROR` state, debugging container builds,
> or recovering a broken project environment.

## Prerequisites

- `nvwb-cli` installed at `$HOME/.nvwb/bin/nvwb-cli`
- A running Workbench context (typically `local`)
- `jq` available on PATH

## Setup Variables

```bash
NVWB="$HOME/.nvwb/bin/nvwb-cli"
CONTEXT="local"
PROJECT="/home/workbench/nvidia-workbench/my-project"
```

## Steps

### 1. Check if the build failed

```bash
BUILD_STATE=$($NVWB status -c "$CONTEXT" -p "$PROJECT" -o json \
| jq -r '.result.Environment.BuildState')
```

### 2. Start the build assistant

```bash
if [ "$BUILD_STATE" = "BUILD_ERROR" ]; then
$NVWB internal build-assistant start -c "$CONTEXT" -p "$PROJECT"
fi
```

### 3. Check build assistant status

Streams until `SUCCEEDED`, `FAILED`, or `STOPPED`:

```bash
$NVWB internal build-assistant status -c "$CONTEXT" -p "$PROJECT" -o json
```

### 4. Acknowledge changes

Required before the next build can proceed:

```bash
$NVWB internal build-assistant acknowledge -c "$CONTEXT" -p "$PROJECT"
```

### 5. Rebuild

```bash
$NVWB build -c "$CONTEXT" -p "$PROJECT"
```