Agent instructions - refine ort-build skill

.agents/skills/ort-build/SKILL.md

@@ -24,7 +24,9 @@ You need `--update` when:
 - New source files are added (some CMake targets use glob patterns, others use explicit file lists — re-run to pick up new files either way)
 - CMake configuration changes (new flags, updated CMakeLists.txt)
 
-You do **not** need `--update` when only modifying existing `.cc`/`.h` files — just use `--build`. Skipping it saves time.
+You do **not** need `--update` when only modifying existing `.cc`/`.h` files in an already-configured build tree — just use `--build`. Skipping it saves time.
+
+For major configuration changes (switching EP set, generator, toolchain, or architecture), prefer a **fresh `--build_dir`** rather than reconfiguring in-place, which can leave stale CMake cache entries.
 
 ## Examples
 
@@ -53,6 +55,9 @@ You do **not** need `--update` when only modifying existing `.cc`/`.h` files —
 
 # Load flags from an option file (one flag per line)
 ./build.sh "@./custom_options.opt" --build --parallel
+
+# Direct build.py invocation (must specify --build_dir)
+python tools/ci_build/build.py --build_dir build/Linux --config Release --build --parallel
 ```
 
 ## Key flags
@@ -61,7 +66,7 @@ You do **not** need `--update` when only modifying existing `.cc`/`.h` files —
 |------|-------------|
 | `--config` | `Debug`, `MinSizeRel`, `Release`, or `RelWithDebInfo` |
 | `--parallel` | Enable parallel compilation (recommended) |
-| `--skip_tests` | Skip running tests after build |
+| `--skip_tests` | When no explicit phase flags are given, suppress the default test phase. Has no effect if `--test` is explicitly passed. |
 | `--build_wheel` | Build the Python wheel package |
 | `--use_cuda` | Enable CUDA EP. Requires `--cuda_home`/`--cudnn_home` or `CUDA_HOME`/`CUDNN_HOME` env vars. On Windows, only `cuda_home`/`CUDA_HOME` is validated. |
 | `--target T` | Build a specific CMake target (requires `--build`; e.g., `onnxruntime_common`, `onnxruntime_test_all`) |
@@ -78,8 +83,9 @@ It may be customized with `--build_dir`.
 ## Agent tips
 
 - **Activate a Python virtual environment** before building. See "Python > Virtual environment" in `AGENTS.md`.
-- **Prefer `python tools/ci_build/build.py` directly** over `build.bat`/`build.sh` when redirecting output. The `.bat` wrapper runs in `cmd.exe`, which breaks PowerShell redirection.
-- **Redirect output to a file** (e.g., `> build_log.txt 2>&1`). Build output is large and will overflow terminal buffers.
-- **Run builds in the background** — a full build can take tens of minutes to over an hour. Poll the log for `"Build complete"` or errors.
+- **Prefer `python tools/ci_build/build.py` directly** over `build.bat`/`build.sh` when redirecting output. The `.bat` wrapper spawns `cmd.exe`, which can cause unreliable output capture — `cmd.exe` and PowerShell handle stream redirection differently, leading to lost or garbled output. Note: when calling `build.py` directly, you **must** pass `--build_dir` (e.g., `--build_dir build/Windows`) — the wrapper scripts inject this automatically, but `build.py` requires it.
+- **Redirect output to a file** (e.g., `> build.log 2>&1`) — build output is large and will overflow terminal buffers. Put log files under the build directory (e.g., `<build_dir>/logs/build.log`) to avoid cluttering the repo root.
+- **Builds are long-running** — a full build can take tens of minutes to over an hour. Run builds in the same session with a long timeout. If the timeout expires, the build continues running — poll infrequently until it finishes. Do not restart or re-launch the build.
+- **After a build completes**, treat exit code 0 as success. If the exit code is nonzero or expected outputs are missing, inspect the log for errors. `"Build complete"` in the log is a confirming success signal for `build.py`. Expected outputs depend on the command: compiled binaries for `--build`, generated CMake files for `--update`, a `.whl` file for `--build_wheel`, etc.
 - **Use `--parallel`** by default unless the user says otherwise.
 - Ask the user what they want to build (config, execution providers, wheel, etc.) if not clear from their prompt.