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:
# 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.
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:
[ "$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 |
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:
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.
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 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.
1---2# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.3# SPDX-License-Identifier: Apache-2.045name: nemo-skill-selection-26description: 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.7triggers:8 - build an agent9 - create an agent10 - deploy an agent11 - set up nemo12 - install nemo13 - try nemo14 - improve my agent15 - help me with nemo16 - nemo helix17 - shut down nemo18 - tear down nemo19 - what is running on nemo20 - help me ship an agent21 - fine-tune embedding22 - retrieval recipe23 - domain retrieval24not-for:25 - setup (use to verify install or to be told how to run the CLI install)26 - nemo-build-agent (use for the actual scaffold/deploy flow)27 - superpowers:brainstorming (use for design work unrelated to NeMo Helix)28 - running downstream workflow or state-changing platform commands (each downstream skill owns its own commands)29 - loading multiple downstream skills in one turn30compatibility: nemo-helix >= 0.1.0; selection plus a host scan on macOS or Linux; works without an installed CLI (selector can pick setup, which then tells the user how to run the CLI install).31maturity: active32license: Apache-2.033user-invocable: true34allowed-tools: Bash35metadata:36 source: https://skillmd.com/skills/nvidia-nemo/nemo-skill-selection-237 author: NeMo Helix Team <nemo-helix@nvidia.com>38---3940# NeMo Helix skill selection4142Decide which downstream NeMo Helix skill should run. Bash access is unrestricted at runtime and43can execute state-changing commands; the scope below is a behavioral constraint, not an enforced44allowlist. Execute only the host scan in this skill's Pre-flight section, then announce the choice45and hand off. Never run downstream workflow or state-changing platform commands from this skill.4647New NeMo Helix agent builds use a Platform-managed `agent.yaml` with48`config_format: nemo-agents-spec-v1` and a supported harness. NVIDIA NeMo Agent49Toolkit (NAT) workflow YAML remains a compatibility path. Do not describe NAT50as the only supported implementation model.5152If an existing agent does not fit a supported harness contract, route based on53the user's goal: preserve an existing NAT workflow, identify a custom adapter,54or use `nemo-agent-config` for a best-effort migration. Do not promise that an55arbitrary Python entrypoint can be converted mechanically.5657## Decision table5859Match the user's intent to one downstream skill. Pick exactly one.6061| The user says or implies | Hand off to | Why |62|---|---|---|63| "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. |64| "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 |65| "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 |66| "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 |67| "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 |68| "create an experiment", "publish evaluation runs", "evaluation leaderboard" | `nemo-experiments-upload` | Create Experiments and Evaluations, ingest their telemetry and scores, and verify leaderboard rollups |69| "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 |70| "shut down", "stop NeMo", "tear down", "clean up" | `nemo-teardown` | Stop the cluster (keep data, delete platform data, or full cleanup) |71| "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. |72| "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. |73| "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. |74| "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. |75| "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. |76| "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. |7778**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`.7980If a request includes both config authoring and deployment, choose81`nemo-build-agent`; it delegates the config portion to `nemo-agent-config`.82Choose `nemo-agent-config` when the requested output stops at a validated config83or migration. Otherwise, if two rows fit, pick the earliest one in the84lifecycle. If nothing matches, ask one disambiguating question with the85relevant rows as a numbered list.8687## Pre-flight8889Before 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`:9091```bash92# 0. Which platform does the active context use? Honors NHX_BASE_URL and NHX_CURRENT_CONTEXT.93# With no config file at the default path, this resolves to http://localhost:8080.94# Prints "no-config" only when there is no CLI install, or NHX_CONFIG_FILE names a missing file.95if [ -x .venv/bin/python ]; then96 NHX_URL=$(.venv/bin/python -c '97from nemo_helix_ext.config.config import get_context98try:99 print(str(get_context().cluster.base_url).rstrip("/"))100except FileNotFoundError:101 print("no-config")102') || { echo "CONFIG_ERROR (see error above)"; exit 1; }103else104 NHX_URL=no-config105fi106echo "$NHX_URL"107```108109If 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>`.110111`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.112113### Remote platform114115If `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.116117```bash118for path in /health/ready /cluster-info; do119 code=$(curl -sS --connect-timeout 2 --max-time 5 "$NHX_URL$path" -o /dev/null -w "%{http_code}" 2>/dev/null || echo "no-response")120 echo "$path $code"121done122```123124| What you observe | Hand off to | Why |125|---|---|---|126| Either path returns `200` | the requested downstream skill | Remote platform is configured and reachable. Tell the user which URL and context you are using. |127| 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. |128129### Local platform130131If `NHX_URL` is local (or `no-config`), run a host-wide platform scan. Three signals, in order — the first one that fires wins:132133```bash134[ "$NHX_URL" = no-config ] && NHX_URL=http://localhost:8080135LOCAL_PORT=$(python3 -c 'import sys; from urllib.parse import urlsplit; print(urlsplit(sys.argv[1]).port or 8080)' "$NHX_URL")136137# 1. Ground truth: is anything listening on the configured port?138lsof -iTCP:"$LOCAL_PORT" -sTCP:LISTEN 2>/dev/null139140# 2. Functional check: does the platform readiness endpoint answer?141curl -sS --connect-timeout 2 --max-time 5 "$NHX_URL/health/ready" -o /dev/null -w "%{http_code}\n" 2>/dev/null || echo "no-response"142143# 3. Conflict check: other platform processes / data dirs / configs on this host?144ps -eo pid=,user=,comm=,args= 2>/dev/null \145 | awk '$0 ~ /[n]emo services (run|start)|[n]emo-platform run/ {print $1, $2, $3}'146ls -d ~/.local/share/nemo* 2>/dev/null147ls ~/.config/nhx*/config.yaml 2>/dev/null148```149150Interpretation:151152| What you observe | Hand off to | Why |153|---|---|---|154| (1) returns a listener AND (2) returns `200` | the requested downstream skill | Platform is up and ready. Skip `setup`. |155| (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. |156| (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. |157| (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`. |158159Read-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.)160161## Starting the platform from a sandboxed agent162163The 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:164165```bash166python3 -c "import socket; s = socket.socket(); s.bind(('127.0.0.1', 0)); s.listen(1); print('LISTEN_OK')" 2>&1 | tail -1167```168169Port 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.170171When 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:172173- **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.174- **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.175- **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).176- **An existing platform elsewhere.** Point `NHX_BASE_URL` at it and skip local startup.177178## What to announce179180Tell 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."181182Then hand off. Do not run downstream workflow or state-changing platform commands from this skill.183184## If nothing matches185186If the user's intent doesn't fit any row, do not guess. Read out the available skills and ask which one they want:187188```189NeMo Helix skills I can route to:190 setup verify install or get the CLI install command191 nemo-agent-config author, validate, or migrate Platform agent.yaml192 nemo-build-agent build from confirmed requirements, register, deploy, evaluate, and sign off193 nemo-try-agent invoke a named deployment or local agent YAML config194 nemo-intake instrument agents, ingest/query telemetry, attach scores195 nemo-experiments-upload publish named evaluation runs to an Experiments leaderboard196 nemo-status read-only platform health dashboard197 nemo-teardown guided shutdown198 nemo-retrieval-recipes embedding/rerank domain fine-tune on Platform plugin jobs199200Plugin-owned skills:201 agents-optimize cost / latency / quality optimization for a deployed agent202 agents-secure safety and security audit for a deployed agent203 nemo-evals-plugin evaluation metrics, LLM-judge, retrieve-eval, benchmark jobs204 nemo-customizer fine-tuning of chat/SFT/RL models (not the retrieval recipe)205 nemo-compass analyze agent telemetry and file recurring problems as Insights206 guardrails content-safety middleware via virtual models207 garak red-team vulnerability scanning (garak)208 nemo-data-designer-plugin synthetic dataset generation (tabular `create`; retrieval SDG is the retrieval recipe)209 anonymizer PII handling for datasets210211Which one fits what you're trying to do?212```213214For 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.215216If the pre-flight finds no platform but the user insists they have installed one: ask them to report217the output of `lsof -iTCP:<port> -sTCP:LISTEN` (the port from `NHX_URL`, usually `8080`) and the redacted scan below from the shell where they ran218setup. The platform may be bound to a non-default port, or the install may be in a venv whose `nemo`219binary is not on `PATH`.220221```bash222ps -eo pid=,user=,comm=,args= 2>/dev/null \223 | awk '$0 ~ /[n]emo services|[n]emo-platform run/ {print $1, $2, $3}'224```225226## If the user asks about Studio (web UI)227228Skills 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.229230What to say:231232- Studio is the NeMo Helix web UI. When the platform is running locally, it serves at `http://localhost:8080/studio`.233- 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.234- **Honest caveats to flag every time:**235 - 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`.236 - Other views may evolve; refer to the docs for the current state rather than promising specific behavior.237- For local development on Studio itself, the source lives at `web/packages/studio/`. The `studio-dev` skill (if available) covers that workflow.238239Do 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.240241## Gotchas242243- **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.244- **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.245- **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.246- **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)."247- **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.248- **Execution compatibility.** New Platform configs must select a supported249 harness. Existing NAT workflows may remain on the NAT compatibility path.250 For another framework or an arbitrary Python entrypoint, inspect whether a251 supported harness owns its lifecycle; otherwise identify a custom adapter or252 NAT wrapper instead of claiming direct support.