3 -description: "Use when writing, debugging, or modernizing Nu code/config, editing .nu files, or translating shell commands to Nushell. Not generic Bash or terminal work."
3 +description: "Use when writing, debugging, or modernizing Nu code/config, or translating shell commands to Nushell."
9 -Target installed Nu, not remembered syntax.
10 -Keep language guidance here; use `mise` for Mise integration
11 -and `linux-userland` for Linux HOME/XDG boundaries.
9 +Target installed Nu, not memory. Keep Nu guidance here; follow project instructions for Mise and OS boundaries.
15 -Use `nu --no-config-file -c '<probe>'` for isolated language checks.
16 -This skips startup config, not inherited env or side effects in the probe.
17 -Never dump `$env`, source secret files,
18 -or run real login startup merely to check syntax.
13 +- Probe isolated: `nu --no-config-file -c '<probe>'`.
14 +- Ask installed Nu: `help <command>`, `help --find <term>`, `scope commands`.
15 +- For migrations, follow [Modernize](references/modernize.md): local help → release notes → isolated probes.
16 +- Use the [Nu book](https://www.nushell.sh/book/), especially [Coming from Bash](https://www.nushell.sh/book/coming_from_bash.html), and [release notes](https://www.nushell.sh/blog/).
21 -version | select version experimental_options
22 -help commands | where name == "path type" | get input_output
23 -help --find semver | select name usage
27 -For deprecated syntax, inspect command metadata when available:
30 -scope commands | where name == "str upcase" | get deprecation_info
33 -For migrations, follow [Modernize](references/modernize.md):
34 -local help, intervening release notes, then isolated behavior checks.
35 -Do not copy website examples without checking the installed CLI.
18 +Never dump `$env`, source secrets, or run real login startup merely to check syntax.
39 22 - Pipelines carry typed values; external programs exchange byte streams.
40 -- Use `$env.NAME` for environment variables and `$row.field?` for optional fields.
41 - `null` has type `nothing`; guard before passing optional paths to filesystem commands.
42 -- `which` returns records, possibly none;
43 - check emptiness before extracting `get 0.path`.
44 -- Use `^cmd` to bypass internal commands; pass argument lists as `^cmd ...$args`.
45 -- Use `and`/`or` for booleans, not `&&`/`||`.
46 - `;` sequences expressions, not conditional success;
47 - external failures can stop execution.
48 -- Use `save` for pipeline values, `o+e> file` for external output to a file,
49 - and `o+e>| filter` for combined output into a pipeline.
50 - Do not put a filename after `o+e>|`.
23 +- Guard optional values before filesystem commands.
24 +- `which` may return nothing: check before `get 0.path`.
25 +- Use `^cmd ...$args` for external commands.
26 +- Use [Bash → Nu](https://www.nushell.sh/book/coming_from_bash.html), not Bash intuition:
30 + | `cmd1 && cmd2` | `cmd1; cmd2` |
31 + | `> file` | `o> file` or `| save file` |
32 + | `> /dev/null` | `| ignore` |
33 + | `> /dev/null 2>&1` | `o+e>| ignore` |
34 + | `$(cmd)` | `(cmd)`; inside strings `$"(cmd)"` |
54 -Capture output and status together instead of assuming
55 -`$env.LAST_EXIT_CODE` behaves like Bash `$?` in every context:
36 + `$"some text(s)"` runs `s`; escape literal parentheses (`\(`, `\)`) or use a plain string.
37 +- Use `save` for pipeline values; `o+e> file` for external output to a file; `o+e>| filter` for combined output.
58 -let result = (^tool ...$args | complete)
59 -if $result.exit_code != 0 {
60 - error make {msg: $"tool exited ($result.exit_code)"}
62 -let data = try { $result.stdout | from json --strict } catch {
63 - error make {msg: "tool returned invalid JSON"}
67 -Use `from json --strict` when the external contract requires JSON;
68 -the default parser accepts non-JSON input too.
69 -Distinguish process failure, malformed data, and valid empty results.
70 -Do not replace failures with `null`, `[]`, or success
71 -unless the caller explicitly permits that fallback.
72 -Do not expose raw stderr or output that may contain secrets.
41 +- Detect the feature first; resolve the executable at invocation time.
42 +- Check lookup before extracting its path; reuse that resolution for the operation.
43 +- Prompt/status with no executable → explicit degraded output, no spawn.
44 +- Explicit user action with no executable → actionable error, never fake success.
45 +- Test present/absent states with identical triggering metadata; hide only the target executable where possible.
74 -##
Config and scripts 76 -1. Identify the actual shell and launch mode:
77 - command string, script, interactive, or login.
78 - Use `$nu | columns`, then inspect only needed config paths,
79 - including `loginshell-path`, `vendor-autoload-dirs`, and `user-autoload-dirs`.
80 -2. Trace loaded files and their generators before editing activation warnings.
81 - Fix the owner or confirmed duplicate; do not patch generated output blindly.
82 -3. `source`, `use`, `run`, and `nu script.nu` are not interchangeable.
83 - Check local help for scope, pipeline input, `main` arguments,
84 - and top-level execution before switching invocation.
85 -4. Treat `$ans` as REPL state, not a script result store.
86 - Check local help before using version-specific argument annotations such as `external_arg`.
87 -5. Preserve typed signatures and error paths;
88 - reproduce type failures before blaming a release
89 - or disabling experimental checks.
49 +- [External process handling](references/external-processes.md)
50 +- [Configuration and scripts](references/configuration.md)
93 -Read the target and its imports first; diagnostics may expose source literals.
94 -For reviewed, non-secret code, run the helper from this skill directory:
54 +Read the target and imports first. For reviewed, non-secret code:
97 57 node scripts/check.mjs /absolute/path/to/file.nu
100 -It runs `nu --no-config-file --ide-check 100`, reports Nu version and diagnostics,
101 -and fails on Error severity even when Nu exits zero.
102 -It does not run the script body; parsing can read imports and evaluate constants,
103 -so this is not a sandbox.
104 -Missing Nu, process failure, stderr, or malformed diagnostics fail closed.
105 -Warnings are reported when emitted, but a pass does not prove absence
106 -of deprecations; Nu 0.115.1 IDE mode omits some.
108 -Then exercise positive and negative behavior with reviewed code
109 -in isolated temporary fixtures.
110 -Check exit codes, data shape, empty/missing inputs, and intended startup mode separately.
111 -Never execute a mutating script just to validate it.
113 -Helper regression tests: `npm test` in this skill directory;
114 -requires Node and Nu on PATH.
61 +The helper checks Nu version and IDE diagnostics; it does not run the script and a pass does not prove runtime correctness or absence of deprecations. Exercise positive/negative behavior in isolated temporary fixtures: present/absent tools, exit codes, data shape, empty/missing input, and startup mode. Never execute a mutating script merely to validate it.