nemotron-customize

What this skill does

# nemotron-customize

IMPORTANT: Read this file before answering any `nemotron-customize`,
Nemotron customization, Curator curation, translation, SFT, PEFT, RL,
conversion, optimization, checkpoint or existing/hosted-endpoint evaluation, or
multi-step pipeline request. This applies whether the user names one step or
asks you to compose several steps into a pipeline.

Evaluation requests count even when no training is involved: "evaluate",
"benchmark", "smoke test", or "score" an existing/hosted endpoint, an API/model
ID, or a deployed model all route to `eval/model_eval`. Read this skill for
those too.

## Purpose

Turn a model-customization request into a repo-native Nemotron step pipeline.
Plan the DAG, validate artifact wiring, and create only the YAML/config files
needed to run existing steps.

Use this skill only for inspecting, configuring, validating, running, or
submitting existing Nemotron steps or multi-step training/customization
pipelines. For frontend, dashboard, visualization, generic ML advice,
billing/access, or unrelated coding tasks, stop with a short scope note and do
not inspect the step catalog or edit files in that turn.

## Prerequisites

- A checkout of the Nemotron repo with `src/nemotron/steps/` present; run from
  the repo root.
- `uv` available to invoke `uv run nemotron steps ...`.
- For remote execution: an env profile TOML (`NEMOTRON_ENV_FILE` or
  `env*.toml`) with a section matching the selected step.
- For hosted services (translation, hosted eval): the auth environment variable
  expected by the step (for example `NVIDIA_API_KEY`), exported in the
  environment — never inlined or committed.
- User-provided concrete values (model/checkpoint, data paths, output dir,
  hardware/GPU count) before any command is presented as runnable.

## Limitations

- Does not invent new catalog steps. When no existing step, runner, recipe, CLI,
  or config can satisfy the request, it names the gap (Explorer mode) instead of
  fabricating a step.
- Produces YAML/config for existing steps; new Python/shell is out of scope
  except in Explorer mode after the gap is approved.
- Not for deployment-only/serving, frontend, dashboards, generic ML advice, or
  non-Nemotron tasks.
- Does not guess concrete values (paths, model IDs, GPU counts, profiles); it
  asks or returns `Blocked` when they are missing.

## Core Rule

Use bundled references first. The `references/` folder is the first decision
surface for routing, artifacts, patterns, hardware heuristics, and command
shape. Use `src/nemotron/steps/...` only as a live verification/fallback source
when you need exact current config fields, manifests, runner imports, or details
missing from bundled references.

If sources disagree:

1. Checked live repo files win for exact execution.
2. Bundled references win for initial routing and planning.
3. Upstream docs/context packs are used only for exceptional code generation
   or library API details.

## Before You Begin

- Read this `SKILL.md` workflow and the relevant bundled reference before
  opening repo source files.
- Route from `references/CATALOG.md` and `references/ARTIFACTS.md` before any
  broad repo exploration. Once a route is determined, verify only the selected
  live step/config/env files needed for the answer.
- Do not emit commands with fake paths, placeholder model IDs, guessed task IDs,
  guessed batch profiles, or default auth variable names presented as facts.
  Ask for missing concrete values or return a `Blocked` handoff.
- Use `references/COMMANDS.md` as the authoritative checklist before
  finalizing configs or execution commands.
- For pipeline requests, plan before editing. Do not create or modify files
  until the DAG, artifact edges, required inputs, and validation checks are
  stated and approved.
- For one-shot command requests, prefer a complete parameterized command in one
  response over exploratory prose, but only after required inputs are known.
  If the user already provides the needed values and asks for only a command,
  answer with the command first and keep explanation minimal.
- Output discipline (keeps responses tight): emit one command block per step,
  include only flags the step actually defines, and add no speculative or
  invented flags. Keep narrative to a few lines — the command plus the required
  safety/profile callouts, not a tutorial. Do not restate reference content the
  user did not ask for.
- Do not spawn subagents for one-shot command lookup. Use the bundled command
  reference directly; verify only the selected step if needed.

## Safety

Keep Bash scoped to repo-safe commands such as `uv run nemotron steps ...`,
targeted tests, `git status/diff`, and config validation. Never run environment
dumps (`env`, `printenv`, broad `export`) or commands that expose secret values.
For remote submissions, destructive changes, or expensive launches, confirm
before execution.

When inspecting env/config files, avoid printing whole files that may contain
secrets. Use targeted reads, report only section names and env-var names, and
redact values for fields containing `token`, `key`, `secret`, `password`,
`credential`, or `auth`.

## Reference Map

| Question | Read first | Live fallback / verification |
|---|---|---|
| Which step or category fits? | `references/CATALOG.md` | `uv run nemotron steps list/show`, then selected `step.toml` |
| Do artifacts chain? | `references/ARTIFACTS.md` | `src/nemotron/steps/types.toml` |
| What run shape should I emit? | `references/COMMANDS.md` | checked-in config YAML plus active profile TOML |
| Remote profile generation or selection | `references/COMMANDS.md` | active `NEMOTRON_ENV_FILE`, `env.toml`, or `env.*.toml` |
| What hardware/backend should I recommend? | `references/HARDWARE.md` | selected step `[[models]]` and `[[strategies]]` |
| Which cross-step guardrails apply? | `references/PATTERNS.md` | `src/nemotron/steps/patterns/<id>.md` |
| How do I run the full workflow? | `references/WORKFLOW.md` | selected step configs, `step.py`, and runners |
| Which upstream library API should generated code use? | `references/context/index.toml` -> matching pack | selected `step.py`, `_runners/`, upstream docs |
| New project scaffold, only when existing repo code cannot support the request | `references/act/PROJECT.md` | existing repo project/recipe shape |
| Per-stage code rules, only when existing repo code cannot support the request | `references/act/STAGE.md` | selected `step.py` and shared runner |

Do not start by reading category READMEs or `step.toml` for ordinary decisions.
Select candidates from bundled references, then verify exact live details before
writing configs or final commands.

## Routing

Use `references/CATALOG.md` as the authoritative home for step selection and
route-specific fast paths. Use `ARTIFACTS.md`, `PATTERNS.md`, and `HARDWARE.md`
only to resolve artifact, cross-step, or hardware constraints after the catalog
narrows the route.

Each step is independent and stitching steps together is your job. Compose any
pipeline by artifact matching from the user's end goal: chain a step only when
the next step consumes an artifact type nothing upstream already produces. Do
not rely on fixed, named step combinations.

## Instructions

Follow the flow that matches the request: a recommendation/plan, a single-step
command, or a multi-step pipeline. In all cases, route from the bundled
references first, gather required inputs, and verify the selected live step
before presenting anything as runnable.

### Recommendation Response

Use this shape for planning answers:

`Decision`, `Why`, `Required inputs`, `Config/command`, `Avoid`, and `Next step`.
Call out the stack to avoid when the user's constraints make it a poor fit.

Whenever the answer includes a command that touches a hosted service or remote
execution, also state, in the answer:

- The auth env-var name and that its value must be exported in the environment,
  never inlined or committed (never