repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skillz/nushell/SKILL.md

Raw

Rendered preview

name: nushell which: nu description: "Use when writing, debugging, or modernizing Nu code/config, or translating shell commands to Nushell." license: MIT

Nushell

Target installed Nu, not memory. Keep Nu guidance here; follow project instructions for Mise and OS boundaries.

Source of truth

Probe isolated: nu --no-config-file -c '<probe>'.
Ask installed Nu: help <command>, help --find <term>, scope commands.
For migrations, follow Modernize: local help → release notes → isolated probes.
Use the Nu book, especially Coming from Bash, and release notes.

Never dump $env, source secrets, or run real login startup merely to check syntax.

Code

Pipelines carry typed values; external programs exchange byte streams.
Guard optional values before filesystem commands.
which may return nothing: check before get 0.path.
Use ^cmd ...$args for external commands.
Use Bash → Nu, not Bash intuition:

Bash Nu

cmd1 && cmd2 cmd1; cmd2

> file o> file or `

> /dev/null `

> /dev/null 2>&1 `o+e>

$(cmd) (cmd); inside strings $"(cmd)"

$"some text(s)" runs s; escape literal parentheses ($, $) or use a plain string.
Use save for pipeline values; o+e> file for external output to a file; o+e>| filter for combined output.

Bash	Nu
`cmd1 && cmd2`	`cmd1; cmd2`
`> file`	`o> file` or `
`> /dev/null`	`
`> /dev/null 2>&1`	`o+e>
`$(cmd)`	`(cmd)`; inside strings `$"(cmd)"`

Optional CLI:

Detect the feature first; resolve the executable at invocation time.
Check lookup before extracting its path; reuse that resolution for the operation.
Prompt/status with no executable → explicit degraded output, no spawn.
Explicit user action with no executable → actionable error, never fake success.
Test present/absent states with identical triggering metadata; hide only the target executable where possible.

Details

Verify

Read the target and imports first. For reviewed, non-secret code:

node scripts/check.mjs /absolute/path/to/file.nu
npm test

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.

---
name: nushell
which: nu
description: "Use when writing, debugging, or modernizing Nu code/config, or translating shell commands to Nushell."
license: MIT
---

# Nushell

Target installed Nu, not memory. Keep Nu guidance here; follow project instructions for Mise and OS boundaries.

## Source of truth

- Probe isolated: `nu --no-config-file -c '<probe>'`.
- Ask installed Nu: `help <command>`, `help --find <term>`, `scope commands`.
- For migrations, follow [Modernize](references/modernize.md): local help → release notes → isolated probes.
- 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/).

Never dump `$env`, source secrets, or run real login startup merely to check syntax.

## Code

- Pipelines carry typed values; external programs exchange byte streams.
- Guard optional values before filesystem commands.
- `which` may return nothing: check before `get 0.path`.
- Use `^cmd ...$args` for external commands.
- Use [Bash → Nu](https://www.nushell.sh/book/coming_from_bash.html), not Bash intuition:

  | Bash | Nu |
  | --- | --- |
  | `cmd1 && cmd2` | `cmd1; cmd2` |
  | `> file` | `o> file` or `| save file` |
  | `> /dev/null` | `| ignore` |
  | `> /dev/null 2>&1` | `o+e>| ignore` |
  | `$(cmd)` | `(cmd)`; inside strings `$"(cmd)"` |

  `$"some text(s)"` runs `s`; escape literal parentheses (`\(`, `\)`) or use a plain string.
- Use `save` for pipeline values; `o+e> file` for external output to a file; `o+e>| filter` for combined output.

Optional CLI:

- Detect the feature first; resolve the executable at invocation time.
- Check lookup before extracting its path; reuse that resolution for the operation.
- Prompt/status with no executable → explicit degraded output, no spawn.
- Explicit user action with no executable → actionable error, never fake success.
- Test present/absent states with identical triggering metadata; hide only the target executable where possible.

## Details

- [External process handling](references/external-processes.md)
- [Configuration and scripts](references/configuration.md)

## Verify

Read the target and imports first. For reviewed, non-secret code:

```sh
node scripts/check.mjs /absolute/path/to/file.nu
npm test
```

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.