---
title: "Set Up Agent Skills for DGX Station — Instructions"
canonical: "https://build.nvidia.com/playbooks/dgx-station-ai-skills/instructions.md"
---

# Step 1. Verify your environment

Confirm the hardware platform has the software the skills expect. Python 3.11 or newer is required by the installer.

```bash
python3 --version
nvidia-smi --query-gpu=name,compute_cap,uuid --format=csv
docker info --format '{{.ServerVersion}}'
```

Expected output should show Python 3.11 or newer, a GB300 GPU reporting compute capability `10.3`, and a running Docker daemon. Note the GPU UUIDs rather than the row order — the `nvidia-smi` index is not a CUDA ordinal on this hardware platform, and the skills always select GPUs by UUID.

# Step 2. Clone the playbook

Clone the playbook repository so the installer and bundled skills are available locally.

```bash
git clone https://github.com/NVIDIA/dgx-spark-playbooks/blob/main/nvidia/playbook-dgx-station-ai-skills
cd nvidia/playbook-dgx-station-ai-skills
```

Everything the installer needs lives under `assets/`: the installer itself, the `dgx-assist.pyz` CLI, and the four skill directories.

# Step 3. Preview the installation

Preview the exact changes before writing anything. The target is the project that should receive the skills — not this playbook directory.

```bash
assets/install.sh install \
--harness codex \
--target /path/to/project \
--dry-run
```

Expected output should show a `WOULD WRITE` line for each skill file, one for `.dgx-station/bin/dgx-assist`, a diff of the managed NVIDIA block that will be added to your context file, and a closing `DRY-RUN: no files changed`.

Choose the `--harness` value that matches your agent:

| Harness | Skill directory | Context file |
|---|---|---|
| `claude` | `.claude/skills/` | `CLAUDE.md` |
| `codex` | `.agents/skills/` | `AGENTS.md` |
| `gemini` | `.gemini/skills/` | `GEMINI.md` |
| `cursor` | `.cursor/skills/` | `AGENTS.md` |
| `all` | every supported harness | managed blocks as applicable |

Each harness receives complete native skill directories with their references, scripts, and UI metadata — never a lossy transformed command or rule.

# Step 4. Install the skills and CLI

If the preview is correct, run the same command without `--dry-run`.

```bash
assets/install.sh install \
--harness codex \
--target /path/to/project
```

The installer backs up an existing context file before its first managed edit, refuses unmanaged skill collisions and symlink destinations, and records every installed hash in `.dgx-station/install-manifest.json`.

To install only the CLI for the current user, when a project-local installation is not appropriate:

```bash
assets/install.sh install-cli --scope user
```

Restart your AI coding agent in the target project so it picks up the new skills and context block.

# Step 5. Verify the installation

Confirm the CLI is present and the bundled content is intact.

```bash
cd /path/to/project
.dgx-station/bin/dgx-assist version
.dgx-station/bin/dgx-assist catalog status
.dgx-station/bin/dgx-assist playbook status
```

Expected output should show the CLI version, a valid bundled catalog, and a healthy playbook search index. You can check the installation itself at any time:

```bash
assets/install.sh status --target /path/to/project
```

# Step 6. Confirm your platform support profile

The skills refuse to guess what your hardware can do. Inspect it and read the resolved profile.

```bash
.dgx-station/bin/dgx-assist system inspect
```

Expected output should show an exact compatibility profile and per-feature
capabilities. The trusted release marker selects one of three profiles. A
profile is selected only when every field of the release identity matches one
recognized identity exactly:

| Profile | Exact release identity | Behavior |
|---|---|---|
| Software 1.0 | `DGX_SWBUILD_VERSION` `7.4.1` or `7.4.1-GB300ws`; `DGX_SWBUILD_DATE` `2026-02-20-05-22-42`; `DGX_PRETTY_NAME` `NVIDIA DGX GB300WS` | Guidance, diagnostics, read-only MIG inspection, and explicitly qualified recipes |
| Software 2.0 | `DGX_SWBUILD_VERSION` `7.5.0`; `DGX_SWBUILD_DATE` `2026-06-16-11-48-10`; `DGX_PRETTY_NAME` `NVIDIA DGX GB300WS` | Capability-scoped qualified workflows |
| Unknown | Any other exact identity | General read-only evidence only |

`DGX_PRETTY_NAME` belongs to the identity of both profiles, not to Software 2.0
alone. A host whose version and build match a profile but whose release name
differs — for example `NVIDIA DGX Server` instead of `NVIDIA DGX GB300WS` — is
reported as unknown, because the shipped validation evidence is recorded
against the complete identity rather than against the build string alone.

Both recognized profiles additionally require this hardware evidence, and the
release marker must pass ownership, file-type, symlink, and mode checks:

| Requirement | Required value |
|---|---|
| Architecture | `aarch64` |
| GB300 compute capability | `10.3` |
| Release marker file | root-owned regular file, not a symlink, not group- or world-writable |

Software 1.0 does not inherit Software 2.0 CDMM, ordering-service, or `vsloshd` expectations. It permits only recipes explicitly validated for its exact profile; MIG mutation and platform fixes remain blocked. A different build is reported as unknown rather than assumed compatible.

# Step 7. Ask your agent for a task

This is the normal way to use the playbook. Open your agent in the target project and make a plain-language request:

```text
Inspect this hardware and explain its compatibility profile and restrictions.
```

```text
Serve Qwen/Qwen2.5-Coder-1.5B-Instruct with vLLM. Show the preflight and wait
for my approval before starting anything.
```

The activated skill runs `dgx-assist --json`, interprets the evidence, carries resolution, report, and plan IDs between commands, and presents the result and approval boundary to you. You never need to read or copy raw JSON in this mode.

The remaining steps show the equivalent direct CLI commands, which are useful for terminal work and for understanding what the agent is doing on your behalf.

# Step 8. Search the pinned NVIDIA guidance

Guidance comes from a bundled multi-source snapshot, not model memory.

```bash
.dgx-station/bin/dgx-assist playbook search "mixed coherency containers"
.dgx-station/bin/dgx-assist playbook search "CPU weight offload HBM forward pass"
.dgx-station/bin/dgx-assist playbook search "ISL KV cache maximum concurrency"
.dgx-station/bin/dgx-assist playbook show RESULT_ID
```

Every retrieved record carries its repository revision, source-file SHA-256, heading, lines, role, and authority class. The snapshot pins the Development Guide at `76a1f6adf1a740699c2efff201377947d90f7fd8`, the GB300 Bring-Up Guide at `2f2d22b2fee4b6a2964045a97b786b86b366b65b`, upstream vLLM `v0.22.1` at `0decac0d96c42b49572498019f0a0e3600f50398` matching NVIDIA vLLM container 26.06, and the NVIDIA vLLM release notes.

Where sources conflict, the current Development Guide overrides older bring-up statements about mixed GPU contexts and device indices; those passages and any credential examples are excluded from retrieval. Retrieval abstains when query terms do not overlap the pinned content — do not fill an abstention with remembered platform commands.

# Step 9. Run the qualified inference recipe

Resolve an exact model ID to a recipe, inspect it, run preflight, then preview the launch.

```bash
.dgx-station/bin/dgx-assist recipe models
.dgx-station/bin/dgx-assist recipe resolve --model Qwen/Qwen2.5-Coder-1.5B-Instruct
.dgx-station/bin/dgx-assist recipe show --recipe-id RECIPE_ID
.dgx-station/bin/dgx-assist recipe preflight --resolution-id RESOLUTION_ID
.dgx-station/bin/dgx-assist recipe run --resolution-id RESOLUTION_ID --dry-run
```

Copy the labeled recipe and resolution IDs from one command to the next; in agent use the skill does this for you. Without `--dry-run` or `--yes`, an interactive terminal shows the action preview and asks for confirmation. A non-interactive caller repeats the command with `--yes` only after showing that preview and obtaining approval. Add `--allow-download` only after every required model and image download is disclosed and approved. If you set a non-local `--bind-host` on `recipe resolve`, the matching `recipe run` also requires an explicit `--allow-external-bind`.

The bundled v1 catalog contains one published Software 1.0 smoke recipe — `Qwen/Qwen2.5-Coder-1.5B-Instruct` on vLLM — bound to its exact model revision, immutable NGC image digest, backend version, release profile, and checksummed qualification evidence. This is a functional smoke claim, not a performance benchmark.

These candidates are bundled but deliberately non-runnable, and will refuse to resolve:

- `nvidia/nemotron-3.5-nano` on vLLM
- `qwen/qwen3.6-27b` on vLLM
- `nvidia/nemotron-3-super-120b-a12b` on vLLM
- `qwen/qwen3.6-27b` on SGLang

Verify and manage a running service, then stop it when finished:

```bash
.dgx-station/bin/dgx-assist recipe status
.dgx-station/bin/dgx-assist recipe stop --service-id SERVICE_ID
```

`recipe stop` revalidates ownership labels and sends SIGTERM only. It never force-kills, and it only ever stops resources recorded as owned by `dgx-assist`.

For additional vLLM launch settings beyond this smoke recipe, see [Serve LLMs with vLLM on One Device](https://build.nvidia.com/playbooks/vllm).

# Step 10. Plan a MIG layout

Inspection is available on recognized Software 1.0 and Software 2.0 profiles. Planning and apply additionally require `mig_mutation=true` and your approval.

```bash
.dgx-station/bin/dgx-assist mig inspect
.dgx-station/bin/dgx-assist mig profiles
.dgx-station/bin/dgx-assist mig plan --layout "DRIVER_PROFILE_IDS_OR_NAMES"
.dgx-station/bin/dgx-assist mig apply --plan-id PLAN_ID --dry-run
```

Expected output should show driver-discovered profiles, the disruption and restoration information for the plan, and — under `--dry-run` — no change to the GPUs. `dgx-assist` never stops active GPU clients to apply a layout.

# Step 11. Run diagnostics

Diagnosis is read-only. Each allowlisted fix is separately previewed, confirmed, verified, and recorded.

```bash
.dgx-station/bin/dgx-assist diagnose run
.dgx-station/bin/dgx-assist diagnose bundle --report-id REPORT_ID
.dgx-station/bin/dgx-assist diagnose fix --report-id REPORT_ID --finding FINDING_ID --dry-run
```

Expected output should show findings correlated to pinned playbook content, and a redacted support bundle path. Bundles and receipts persist redacted argv and credential variable names only, never secret values.

# Step 12. Cleanup

Remove the skills, the CLI, and the managed context block from a project.

> [!WARNING]
> This deletes every file recorded in `.dgx-station/install-manifest.json` and removes the delimited NVIDIA block from your context file. Managed files you modified are preserved, and unrelated context is left untouched.

```bash
assets/install.sh uninstall --target /path/to/project --dry-run
assets/install.sh uninstall --target /path/to/project
```

To remove a user-scope CLI and the local caches as well:

```bash
rm -f ~/.local/bin/dgx-assist
rm -rf ~/.cache/dgx-assist ~/.local/state/dgx-assist
```

# Step 13. Next steps

Keep an installation current, or migrate one made by an older release:

```bash
assets/install.sh update --target /path/to/project --dry-run
assets/install.sh update --target /path/to/project
assets/install.sh migrate --target /path/to/project --dry-run
assets/install.sh migrate --target /path/to/project
```

Migration removes a released legacy skill only when its exact artifact hash is known; modified legacy skills remain with a warning. Update and uninstall operate only on manifest-owned files and delimited context blocks.

1. **Automate with the JSON envelope.** Every command accepts `--json` anywhere in its arguments and returns `schema_version`, `command`, `ok`, `data`, `warnings`, and `provenance`. Errors use the same envelope with an `error` object. Never parse the human display in automation.

```bash
.dgx-station/bin/dgx-assist system inspect --json |
jq '.data.compatibility | {profile_id, support_level, capabilities}'
```

2. **Branch on stable exit classes.** Inspect both the process exit code and the JSON `error.code`.

| Exit code | Meaning |
|---:|---|
| `0` | Success |
| `2` | Invalid command, configuration, or input |
| `3` | Unsupported platform or operation |
| `4` | No eligible exact recipe |
| `5` | Safety, approval, staleness, conflict, or policy block |
| `6` | Authorized action or internal operation failed |

3. **Relocate configuration and state.** Unless XDG environment variables override them, configuration lives at `~/.config/dgx-assist/config.json`, caches at `~/.cache/dgx-assist/`, and resolutions, diagnostics, service ownership, receipts, and MIG plans at `~/.local/state/dgx-assist/`.

4. **Point at a live content endpoint.** The public package uses its bundled snapshot and is entirely offline by default. You can optionally supply endpoint configuration in the XDG config file or via `--config PATH`:

```json
{
"catalog": {
"manifest_url": "https://approved.example/catalog/manifest.json",
"allowed_hosts": ["approved.example"]
},
"playbook": {
"manifest_url": "https://approved.example/playbook/manifest.json",
"allowed_hosts": ["approved.example"]
}
}
```

Refresh accepts HTTPS from explicit hosts, validates schema, key ID, Ed25519 signature through OpenSSL, digest, generation time, and expiry, then atomically activates the artifact. A failed refresh retains the last-known-good content. Use `--offline` to suppress the 24-hour bounded refresh attempt, or `catalog refresh --dry-run` and `playbook refresh --dry-run` to inspect the configured host and cache impact without network access.

5. **Tune inference with sourced guidance.** Name the exact model and describe the workload's ISL, generated-output distribution, target concurrency, latency and throughput goals, and repeated-prefix rate. The inference skill explains NGC versus upstream containers, GPU-memory headroom, weight and KV offload, HBM placement, KV-cache sizing, prefix caching, and chunked prefill — without turning those recommendations into launch flags. Changed parameters stay non-executable until an exact recipe is physically validated.

A successful end state is an agent in your project that inspects the real hardware before advising, cites pinned NVIDIA guidance with provenance, and stops for your approval before every mutation.