# Nemo Skill Selection

> Top-level skill selector for ambiguous tasks involving NeMo Helix (NVIDIA's agent platform). Picks the right downstream skill for setup, design, specification, agent configuration, build, deployment, testing, observability, status, teardown, evaluation, optimization, security, or model customization. Use when the user needs help deciding where a NeMo Helix task should start.

- Skill: `nvidia-nemo/nemo-skill-selection-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add nvidia-nemo/nemo-skill-selection-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia-nemo/nemo-skill-selection-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: NVIDIA NeMo (https://skillmd.com/u/nvidia-nemo)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/nvidia-nemo/nemo-skill-selection-2

---


# NeMo Helix skill selection

Decide which downstream NeMo Helix skill should run. Bash access is unrestricted at runtime and
can execute state-changing commands; the scope below is a behavioral constraint, not an enforced
allowlist. Execute only the host scan in this skill's Pre-flight section, then announce the choice
and hand off. Never run downstream workflow or state-changing platform commands from this skill.

New NeMo Helix agent builds use a Platform-managed `agent.yaml` with
`config_format: nemo-agents-spec-v1` and a supported harness. NVIDIA NeMo Agent
Toolkit (NAT) workflow YAML remains a compatibility path. Do not describe NAT
as the only supported implementation model.

If an existing agent does not fit a supported harness contract, route based on
the user's goal: preserve an existing NAT workflow, identify a custom adapter,
or use `nemo-agent-config` for a best-effort migration. Do not promise that an
arbitrary Python entrypoint can be converted mechanically.

## Decision table

Match the user's intent to one downstream skill. Pick exactly one.

| The user says or implies | Hand off to | Why |
|---|---|---|
| "set up", "install", "get started", "try NeMo", "first time" | `setup` | Verify the platform is installed and running. If not, the skill tells the user how to run the CLI install (`make bootstrap` + `nemo setup`). Install itself is CLI-only. |
| "write agent.yaml", "validate agent.yaml", "choose a harness", "migrate this NAT YAML", "convert to nemo-agents-spec-v1" | `nemo-agent-config` | Author or migrate the Platform-managed machine-readable config without running the full build |
| "build the agent", "create the agent", "deploy", "implement these requirements" | `nemo-build-agent` | Build from confirmed requirements, default to Platform `agent.yaml`, register, deploy, evaluate, and optionally apply guardrails |
| "ask my agent", "try the agent", "test it", "invoke this agent.yaml" | `nemo-try-agent` | Invoke a named deployment or run a local agent YAML config once |
| "instrument my agent", "send traces", "use Intake", "agent observability", "query spans or traces" | `nemo-intake` | Choose an ingest path, instrument the source, ingest telemetry, and verify spans, traces, sessions, or evaluator results |
| "create an experiment", "publish evaluation runs", "evaluation leaderboard" | `nemo-experiments-upload` | Create Experiments and Evaluations, ingest their telemetry and scores, and verify leaderboard rollups |
| "status", "what is running", "platform health", "is the platform up", "what's deployed", "show me what's running" | `nemo-status` | Read-only dashboard: platform, agents, providers, models |
| "shut down", "stop NeMo", "tear down", "clean up" | `nemo-teardown` | Stop the cluster (keep data, delete platform data, or full cleanup) |
| "fine-tune embedding", "fine-tune rerank", "retrieval recipe", "domain corpus retrieval", "Nemotron embed", "Nemotron rerank", "retrieve-eval", "nDCG on my documents" | `nemo-retrieval-recipes` | Cross-plugin embed/rerank recipe: Data Designer retrieval jobs, Automodel `bi_encoder`/`cross_encoder`, Evaluator `retrieve-eval`. Not chat SFT. |
| "fine-tune", "customize the model", "train on my data", "SFT", "LoRA" | `nemo-customizer` | Chat/SFT/LoRA/DPO/GRPO via customization contributor plugins. Embedding/rerank domain pipelines go to `nemo-retrieval-recipes` first. |
| "why does my agent keep failing", "analyze my agent's traces", "find recurring failure patterns", "generate insights for my agent" | `nemo-compass` (plugin-owned, in `plugins/nemo-compass`) | Reads an agent's existing telemetry and files each recurring failure pattern as an Insight citing the traces that evidence it. Requires the Compass plugin. |
| "optimize my agent", "make it cheaper", "reduce latency", "smaller model", "switchyard", "routing split", "compare against a newer model" | `agents-optimize` (plugin-owned, in `plugins/nemo-agents`) | Cost / latency / quality optimization for a **deployed** agent. Routing splits, skill tuning, prompt tuning, new-model scans. |
| "secure my agent", "harden my agent", "check for PII", "leaked secrets", "guardrail coverage" | `agents-secure` (plugin-owned, in `plugins/nemo-agents`) | Safety and security audit for a **deployed** agent. Guardrails, PII, secrets scan. |
| "evaluate my agent", "run a benchmark", "eval suite" | `nemo-evals` (plugin-owned, in `plugins/nemo-evals`) | Evaluation metrics, LLM-judge, benchmark jobs against a deployed agent or model. |

**Optimize vs build:** Do NOT route optimize asks to `nemo-build-agent`. Build is for creating new agents from a spec. Use `agents-optimize` for a deployed agent's routing, prompts, skills, cost, or latency. If the user says "make my agent faster" or "use a cheaper model," that is `agents-optimize`, not `nemo-build-agent`.

If a request includes both config authoring and deployment, choose
`nemo-build-agent`; it delegates the config portion to `nemo-agent-config`.
Choose `nemo-agent-config` when the requested output stops at a validated config
or migration. Otherwise, if two rows fit, pick the earliest one in the
lifecycle. If nothing matches, ask one disambiguating question with the
relevant rows as a numbered list.

## Pre-flight

Before handing off, find out which platform the CLI points at. `nemo setup` can connect the active context to a remote cluster, so do not assume `localhost:8080`:

```bash
# 0. Which platform does the active context use? Honors NHX_BASE_URL and NHX_CURRENT_CONTEXT.
#    With no config file at the default path, this resolves to http://localhost:8080.
#    Prints "no-config" only when there is no CLI install, or NHX_CONFIG_FILE names a missing file.
if [ -x .venv/bin/python ]; then
  NHX_URL=$(.venv/bin/python -c '
from nemo_helix_ext.config.config import get_context
try:
    print(str(get_context().cluster.base_url).rstrip("/"))
except FileNotFoundError:
    print("no-config")
') || { echo "CONFIG_ERROR (see error above)"; exit 1; }
else
  NHX_URL=no-config
fi
echo "$NHX_URL"
```

If this prints `CONFIG_ERROR`, the CLI config exists but the active context cannot be resolved (for example, `NHX_CURRENT_CONTEXT` names a missing context). Stop and show the user the error. Do not fall through to the local scan, and do not route to `setup`; suggest `nemo config view --all-contexts` and `nemo config use-context <name>`.

`nemo --help` prints the same information on its first line (`Active context: <name> (workspace: <ws>, platform: <url>)`), and `nemo config view` shows the full active context.

### Remote platform

If `NHX_URL` is set and its host is not `localhost`, `127.0.0.1`, or `::1`, the user has already run `nemo setup` against a remote cluster. Probe only that URL. Do not use the local port and process scans below, and do not suggest `nemo setup` as an install step.

```bash
for path in /health/ready /cluster-info; do
  code=$(curl -sS --connect-timeout 2 --max-time 5 "$NHX_URL$path" -o /dev/null -w "%{http_code}" 2>/dev/null || echo "no-response")
  echo "$path $code"
done
```

| What you observe | Hand off to | Why |
|---|---|---|
| Either path returns `200` | the requested downstream skill | Remote platform is configured and reachable. Tell the user which URL and context you are using. |
| Neither path returns `200` | **stop, do not hand off yet** | The configured remote is unreachable from here (VPN, sandbox network policy, expired credentials, or cluster down). Report the URL and codes, then ask the user to check it. Offer `nemo config view` to inspect or `nemo config use-context <name>` to switch contexts. |

### Local platform

If `NHX_URL` is local (or `no-config`), run a host-wide platform scan. Three signals, in order — the first one that fires wins:

```bash
[ "$NHX_URL" = no-config ] && NHX_URL=http://localhost:8080
LOCAL_PORT=$(python3 -c 'import sys; from urllib.parse import urlsplit; print(urlsplit(sys.argv[1]).port or 8080)' "$NHX_URL")

# 1. Ground truth: is anything listening on the configured port?
lsof -iTCP:"$LOCAL_PORT" -sTCP:LISTEN 2>/dev/null

# 2. Functional check: does the platform readiness endpoint answer?
curl -sS --connect-timeout 2 --max-time 5 "$NHX_URL/health/ready" -o /dev/null -w "%{http_code}\n" 2>/dev/null || echo "no-response"

# 3. Conflict check: other platform processes / data dirs / configs on this host?
ps -eo pid=,user=,comm=,args= 2>/dev/null \
  | awk '$0 ~ /[n]emo services (run|start)|[n]emo-platform run/ {print $1, $2, $3}'
ls -d ~/.local/share/nemo* 2>/dev/null
ls ~/.config/nhx*/config.yaml 2>/dev/null
```

Interpretation:

| What you observe | Hand off to | Why |
|---|---|---|
| (1) returns a listener AND (2) returns `200` | the requested downstream skill | Platform is up and ready. Skip `setup`. |
| (1) returns a listener but (2) returns `no-response` or non-200 | `nemo-status` | Something is bound to the platform port but the platform is not ready. Do not start a second platform. |
| (1) empty but (3) finds another `nemo services` process OR more than one data dir / config | **stop, do not hand off yet** | Another install on this host, possibly on a different port. Surface only the redacted PID, user, and executable inventory emitted above. Ask whether to tear that one down first, pick a different port + data dir, or abort. Two installs writing to the same `~/.config/nhx/config.yaml` is how users end up with one Studio frontend pointing at the wrong backend. |
| (1), (2), and (3) all empty | `setup`, after [Starting the platform from a sandboxed agent](#starting-the-platform-from-a-sandboxed-agent) | Clean machine, no platform running. Check whether you can host it before anything runs `nemo setup` or `nemo services run`. |

Read-only callers (this skill, `nemo-status`, the build/try pre-flights) should not trust `nemo services status` or `nemo services ls` as an up-check. Both report stale "running" from a held instance lock after the underlying process has died. The lock reconciles automatically the next time `nemo services run` is invoked, but until that happens, `lsof` is ground truth. (Tracking a CLI-side fix for this so we can drop the workaround from skills.)

## Starting the platform from a sandboxed agent

The platform is a long-running server. Coding agents often run shell commands inside a sandbox (for example the macOS Seatbelt sandbox in Claude Code) that denies listening sockets, so `nemo services run` and `nemo setup --start-services` fail there no matter which port you pick. Even where the bind is allowed, a server started from an agent's shell inherits its sandbox and usually dies with the session. Probe before starting anything:

```bash
python3 -c "import socket; s = socket.socket(); s.bind(('127.0.0.1', 0)); s.listen(1); print('LISTEN_OK')" 2>&1 | tail -1
```

Port 0 can never be taken, so `PermissionError: [Errno 1] Operation not permitted` means this shell may not host the platform. `LISTEN_OK` means it can. Any other output (for example, `python3` not found) is inconclusive; resolve it before deciding. If `nemo services run` already failed with `Not permitted to listen on ...`, the CLI ran this check for you.

When the probe confirms a denial, or the user wants the platform to outlive this session, **stop and ask the user** how the platform should be hosted. Do not retry on other ports, do not hunt for a process holding the port, and do not bypass the sandbox on your own. Learn enough about the environment to make the options concrete (OS, whether this is a laptop or a shared server, whether Docker is available, whether a platform already runs elsewhere), then offer:

- **The user starts it in their own terminal.** They run `nemo setup` (first time) or `nemo services start` (later) outside the agent. Continue once `curl -sf http://localhost:8080/health/ready` answers from your shell.
- **You run it outside the sandbox for this session.** Only if your harness supports it and the user explicitly approves. The server stops when the session ends.
- **A persistent service.** A user-level service manager (a `systemd --user` unit on Linux, a launchd agent on macOS) or a container the user already runs. Ask which one they use before writing any unit or compose file; it needs the same environment as an interactive start (provider API keys, `NHX_DATA_DIR` if set).
- **An existing platform elsewhere.** Point `NHX_BASE_URL` at it and skip local startup.

## What to announce

Tell the user, in one sentence, which skill is next and what it will do. For example: "Handing off to `setup` to verify the platform is installed and running. If it isn't, the skill will tell you the CLI command to run; install is a 5-minute shell step that this skill cannot do reliably for you."

Then hand off. Do not run downstream workflow or state-changing platform commands from this skill.

## If nothing matches

If the user's intent doesn't fit any row, do not guess. Read out the available skills and ask which one they want:

```
NeMo Helix skills I can route to:
  setup           verify install or get the CLI install command
  nemo-agent-config  author, validate, or migrate Platform agent.yaml
  nemo-build-agent  build from confirmed requirements, register, deploy, evaluate, and sign off
  nemo-try-agent  invoke a named deployment or local agent YAML config
  nemo-intake     instrument agents, ingest/query telemetry, attach scores
  nemo-experiments-upload  publish named evaluation runs to an Experiments leaderboard
  nemo-status     read-only platform health dashboard
  nemo-teardown   guided shutdown
  nemo-retrieval-recipes  embedding/rerank domain fine-tune on Platform plugin jobs

Plugin-owned skills:
  agents-optimize   cost / latency / quality optimization for a deployed agent
  agents-secure     safety and security audit for a deployed agent
  nemo-evals-plugin  evaluation metrics, LLM-judge, retrieve-eval, benchmark jobs
  nemo-customizer   fine-tuning of chat/SFT/RL models (not the retrieval recipe)
  nemo-compass      analyze agent telemetry and file recurring problems as Insights
  guardrails        content-safety middleware via virtual models
  garak           red-team vulnerability scanning (garak)
  nemo-data-designer-plugin  synthetic dataset generation (tabular `create`; retrieval SDG is the retrieval recipe)
  anonymizer        PII handling for datasets

Which one fits what you're trying to do?
```

For things outside this catalog (for example, "show me how Switchyard routes between models"), point at the relevant repo skill (`nemo-evals`, `garak`, etc.) or tell the user no skill claims that intent yet. Do not invent a path.

If the pre-flight finds no platform but the user insists they have installed one: ask them to report
the output of `lsof -iTCP:<port> -sTCP:LISTEN` (the port from `NHX_URL`, usually `8080`) and the redacted scan below from the shell where they ran
setup. The platform may be bound to a non-default port, or the install may be in a venv whose `nemo`
binary is not on `PATH`.

```bash
ps -eo pid=,user=,comm=,args= 2>/dev/null \
  | awk '$0 ~ /[n]emo services|[n]emo-platform run/ {print $1, $2, $3}'
```

## If the user asks about Studio (web UI)

Skills route through CLI commands, not Studio. But customers ask "what's Studio?" or "do you have a web UI?" Answer honestly, do not invent capabilities, and do not steer users into the experimental flows.

What to say:

- Studio is the NeMo Helix web UI. When the platform is running locally, it serves at `http://localhost:8080/studio`.
- Documentation: `docs/studio/index.md` in this repo covers the stable views (Agents, Optimizations, Monitor, Workspaces, Datasets). Point users there rather than enumerating features in-conversation — the docs stay up to date, this skill won't.
- **Honest caveats to flag every time:**
  - The **Optimizations "Apply suggestion"** flow is **incomplete today**. Suggestions render, but the apply action is not reliable end-to-end. Tell the user to apply optimizer suggestions via the CLI (`nemo agents …`) instead, using the suggestion's `apply` block as the source of truth — see `agents-optimize`.
  - Other views may evolve; refer to the docs for the current state rather than promising specific behavior.
- For local development on Studio itself, the source lives at `web/packages/studio/`. The `studio-dev` skill (if available) covers that workflow.

Do not proactively suggest Studio as the path for anything a skill already covers (chat, deploy, status, teardown, optimization). The CLI path is what these skills verify and what we can confidently support.

## Gotchas

- **One skill at a time.** Do not load more than one downstream skill in the same turn. Each downstream skill is a full procedure with its own context budget.
- **Install must happen before any skill can do useful work.** Build, try, and status all assume the platform is up. If the user has not run the CLI install (`make bootstrap` + `nemo setup`), the skills cannot work around that; hand them to `setup` for instructions.
- **A sandboxed shell cannot host the platform.** `Not permitted to listen on ...` from `nemo services run` or `nemo setup` is a sandbox denial, not a port conflict. Follow [Starting the platform from a sandboxed agent](#starting-the-platform-from-a-sandboxed-agent) and ask the user how to host it.
- **NeMo Helix is the product name.** Capital N, e, M, o, P. Not "nemo" or "Nemo." NAT on first mention is "NVIDIA NeMo Agent Toolkit (NAT)."
- **Model customization** for chat/SFT/RL goes to the `nemo-customizer` plugin skill when `nemo-customizer-plugin` (and a training backend) are installed. **Embedding and reranking recipes** (domain corpus, retrieval SDG, `bi_encoder` / `cross_encoder`, `retrieve-eval`) go to `nemo-retrieval-recipes`. If those skills are not available, tell the user to enable the plugins and install skills — do not improvise training with an external library.
- **Execution compatibility.** New Platform configs must select a supported
  harness. Existing NAT workflows may remain on the NAT compatibility path.
  For another framework or an arbitrary Python entrypoint, inspect whether a
  supported harness owns its lifecycle; otherwise identify a custom adapter or
  NAT wrapper instead of claiming direct support.

