Skip to content
Skills Library
Programming · Building & coding

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.

Repository
dotfiles ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

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

  1. Why Nushell
  2. Steps
  3. Docs
  4. Rules
  5. In this repo
Original SKILL.md headings · 65 lines, 539 words
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

RepositoryScoreLicence
This page · ryoppippi/dotfiles100MIT
hakula139/plugins100MIT
DaRacci/nix-config100MIT
vinnie357/claude-skills100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.