> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/ai-workbench/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/ai-workbench/_mcp/server.

# 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](/ai-workbench/how-to/cli/cli-scripting) 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](/ai-workbench/concepts/sandboxing-concept) 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](/ai-workbench/reference/user-interface/cli#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.**

````markdown
# 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.**

````markdown
# 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"
```
````

## Related Topics

- [Using the CLI Binary for Scripts and Agents](/ai-workbench/how-to/cli/cli-scripting) - Calling convention, JSON shapes, state machine, and patterns
- [AI Workbench Command Line Interface (CLI) Reference](/ai-workbench/reference/user-interface/cli) - CLI command reference
- [Build Assistant](/ai-workbench/reference/user-interface/cli#build-assistant) - Build assistant commands
- [Sandboxing Agents with AI Workbench](/ai-workbench/concepts/sandboxing-concept) - Sandboxing for coding agents
- [Interactive CLI Use](/ai-workbench/how-to/cli/cli-interactive) - Interactive CLI use