nushell
/nushell
Write idiomatic, functional Nushell — the default language for shell scripts here. Use when writing or reviewing any new script, .nu files, `shell: nu {0}` CI steps, or when porting bash/POSIX shell to Nushell.
- Author
- ryoppippi ↗
- Repository
- dotfiles ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 6
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Write idiomatic, functional Nushell — the default language for shell scripts here. Use when writing or reviewing any new script, .nu files, `shell: nu {0}` CI steps, or when porting bash/POSIX shell to Nushell.
Original author description
Write idiomatic, functional Nushell — the default language for shell scripts here. Use when writing or reviewing any new script, .nu files, `shell: nu {0}` CI steps, or when porting bash/POSIX shell to Nushell.
How it works
- Why Nushell
- Steps
- Docs
- Rules
- In this repo
SKILL.md preview
---
name: nushell
description: 'Write idiomatic, functional Nushell — the default language for shell scripts here. Use when writing or reviewing any new script, .nu files, `shell: nu {0}` CI steps, or when porting bash/POSIX shell to Nushell.'
---
# Nushell
Nushell is a functional, structured-data language that happens to be a shell. Write it that way: pipelines of transformations over records and tables, not bash with different syntax.
## Why Nushell
Functional over structured data: JSON, `ls`, and command output stay records through the whole pipeline instead of being re-parsed as text. So no `jq`/`sed`/`awk`/`date` to install, wrap, or write twice for macOS and Linux — and Nix pins the interpreter.
Which language to pick for a given script is in the repo's `AGENTS.md`.
## Steps
1. Read the docs for the topic at hand (see below) before writing any Nushell.
2. Write the code functionally — see Rules.
3. Verify every construct against the installed version before claiming it works. Nushell breaks and renames things between minor releases, so do not trust memory of a command's signature:
```sh
nu --version
nu -c '<snippet>' # run a snippet
nu --ide-check 10 <file> # parse/typecheck a script
nu -c 'help <command>' # check a signature
```
4. Format before committing:
```sh
nufmt <file> # rewrites in place
nufmt --dry-run <file> # non-zero exit if it would change
```
## Docs
Read before writing:
- https://www.nushell.sh/book/thinking_in_nu.html
- https://www.nushell.sh/book/nushell_map_functional.html
- https://www.nushell.sh/book/nushell_map_imperative.html
- https://www.nushell.sh/book/coming_to_nu.html
- https://www.nushell.sh/book/style_guide.html
Every page of the book is in the sidebar of those, as are `/commands/`, `/cookbook/`, and `/lang-guide/`. Follow the sidebar to whatever the task needs instead of guessing.
## Rules
Functional style is the default. In review, treat each of these as a defect to fix:
- **`mut` + `for` as an accumulator.** Replace with `reduce`, `each`, `where`, `group-by`, `zip`, `flatten`, `insert`/`update`, `generate`. `mut` is legitimate only for genuinely sequential state that no filter expresses.
- **String plumbing between steps.** Pass records and tables. Serialise once at the boundary (`to json --raw`), parse once on the way in (`from json`).
- **Nested `if`/`else` chains on a value's shape.** Use `match`, including list patterns (`[]`, `[$first, ..$rest]`) and guards.
- **Reimplementing a builtin.** Check `https://www.nushell.sh/commands/categories/filters.html` first.
- **Shelling out for data.** Prefer native commands over `^jq`, `^sed`, `^awk`, `^date`. When an external command is genuinely needed, pipe its output through `from json` etc. immediately.
- **Bare `each` for effects.** If the result is unused, say so with `| ignore`; if it produces values, keep them in the pipeline.
Also:
- Give every script a `def main`.
- Type custom command signatures — parameter types, `--flag`, and the return type. They document intent and are checked at parse time. `nufmt` strips a redundant `: any`; leave it stripped.
- Timestamps are `datetime`, durations are `duration`. Compare and subtract them directly instead of formatting to strings. Convert explicitly to UTC (`| date to-timezone UTC`) when the value crosses a boundary that expects it.
- Fail loudly with `error make` rather than returning a sentinel value.
## In this repo
- CI workflow steps run Nushell via `shell: nu {0}` with `hustcer/setup-nu`. See `.github/workflows/_update-flake-reusable.yaml` for the established style.
- Pin the interpreter. Workflows pass an explicit `version:` to `setup-nu`; keep doing that, or a Nushell release will break a script that never changed.
- Standalone scripts live alongside their consumer, e.g. `nix/packages/git-wtpr/git-wtpr.nu`.
- Neither `nu` nor `nufmt` is on the interactive PATH; use the `missing-tools` skill to reach them.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · ryoppippi/dotfiles | 100 | MIT |
| hakula139/plugins | 100 | MIT |
| DaRacci/nix-config | 100 | MIT |
| vinnie357/claude-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version c3a2cc41a673 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100nushell-usage
Essential patterns, idioms, and gotchas for writing Nushell code. Use when writing Nushell scripts, functions, or working with Nushell's type system, pipelines, and data structures. Complements plugin development knowledge with practical usage patterns. - 100nushell-plugin-builder
Guide for creating Nushell plugins in Rust using nu_plugin and nu_protocol crates. Use when users want to build custom Nushell commands, extend Nushell with new functionality, create data transformations, or integrate external tools/APIs into Nushell. Covers project setup,… - 100koopa-nushell
Nushell (nu) pitfalls, parse-time constraints, and koopa activation architecture. Use when writing or debugging .nu files, editing lang/nushell/include/header.nu or any activate-*.nu, sourcing prompt tools (starship, zoxide), or porting shell logic from bash/zsh/fish to nushell. - 100shell-expert
Shell scripting: bash, zsh, POSIX, CLI tools, cross-platform automation. Use when writing shell scripts, pipes, command-line automation, or portable shell code. - 100gum-nushell
Use Gum from Nushell scripts to build interactive CLI/TUI flows. Trigger when writing, reviewing, or debugging Nu scripts that call `gum` commands such as choose, filter, confirm, input, write, file, table, spin, style, format, join, pager, log, or version-check, especially when… - 100shell-portability
Use when writing shell scripts that need to run across different systems, shells, or environments. Covers POSIX compatibility and platform differences.