Add Nushell Agent Skill (#1231)

This is the skill I use for working with Nushell in my agent TUIs. It's
been tested to identify the most common issues I've come across while
using Nushell with LLMs, and so far in testing has all but eliminated
failing tool calls due to the model misunderstanding how to use Nushell.

Author: 0x4D5352

skills/README.md

@@ -0,0 +1,27 @@
+# Agent Skills
+
+This directory holds examples for use with coding agents that interact with Nu,
+either as a CLI tool or via the Nushell MCP server.
+
+## Nushell Skill
+
+`./skills/nushell/` - An [Agent Skills](https://agentskills.io/home) compliant
+skill directory built via the Claude Code skill-writer superpower and human-tested
+for validity and efficacy. Once added to the appropriate location, begin a new
+session with your coding agent and it should automatically register the skill
+and use it when you reference Nushell, mention the skill directly, or trigger a
+use case mentioned in the description of the SKILL.md frontmatter.
+
+### Global usage
+
+Copy the `nushell/` directory to `~/.claude/skills/` for global use in Claude Code,
+to `~/.copilot/skills` for global use with the Copilot coding agent or GitHub
+Copilot CLI, or to `~/.agent/skills/` for Codex, OpenCode, and other coding agents.
+See your preferred LLM provider's documentation for specific details.
+
+### Project usage
+
+If you only wish to load this skill for specific projects, or for use with non-
+CLI based coding agents that canot access a global skills directory, create a
+`.claude/skills/`, `.github/skills/`, or `.agents/skills/` directory at the root
+of your project and copy the nushell skill directory into it.

skills/nushell/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: nushell
+description: Use when writing or running Nushell commands, scripts, or pipelines - via the Nushell MCP server (mcp__nushell__evaluate), via Bash (nu -c), or in .nu script files. Also use when working with structured data (JSON, YAML, TOML, CSV, Parquet, SQLite), doing ad-hoc data analysis or exploration, or when the user's shell is Nushell.
+---
+
+# Using Nushell
+
+Nushell is a structured-data shell. Commands pass **tables, records, and lists** through pipelines - not text.
+
+**Two execution paths:**
+- **MCP server**: `mcp__nushell__evaluate` - persistent REPL (variables survive across calls)
+- **Bash tool**: `nu -c '<code>'` - one-shot (use single quotes for outer wrapper)
+
+## Critical Rules
+
+**NEVER use bare `print` in MCP stdio mode.** Output will be lost (returns empty `[]`). Use `print -e "msg"` for stderr, or just return the value (implicit return).
+
+**String interpolation uses parentheses, NOT curly braces:**
+```nu
+# WRONG:  $"hello {$name}"
+# CORRECT: $"hello ($name)"
+$"($env.HOME)/docs"    $"2 + 2 = (2 + 2)"    $"files: (ls | length)"
+```
+Gotcha: `$"(some text)"` errors - parens are evaluated as code. Escape literal parens: `\(text\)`.
+
+**No bash syntax:** `cmd1; cmd2` not `&&`, `o+e>|` not `2>&1`, `$env.VAR` not `$VAR`, `(cmd)` not `$(cmd)`.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| `$"hello {$name}"` | `$"hello ($name)"` |
+| `print "msg"` in MCP | `print -e "msg"` or return value |
+| `command 2>&1` | `command o+e>\| ...` |
+| `$HOME/path` | `$env.HOME` or `$"($env.HOME)/path"` |
+| `export FOO=bar` | `$env.FOO = "bar"` |
+| Mutating in closure | Use `reduce`, `generate`, or `each` |
+| `\u001b` for ANSI | `ansi strip` to remove, `char --unicode '1b'` for ESC |
+| `where ($in.a > 1) and ($in.b > 2)` | Second `$in` rebinds to bool. Use bare cols: `where a > 1 and b > 2` |
+| `where not ($in.col \| cmd)` | `not` breaks `$in`. Use `where ($in.col \| cmd) == false` |
+| `where col \| cmd` (no parens) | Parsed as two pipeline stages. Use `where ($in.col \| cmd)` |
+
+## When to Use Nushell
+
+**Always prefer Nushell for:**
+- Any structured data (JSON, YAML, TOML, CSV, Parquet, SQLite) - unifies all formats
+- CLI tools with `--json` flags - pipe JSON output directly into Nushell for querying (e.g. `^gh pr list --json title,state | from json`)
+- Ad-hoc data analysis and exploration - faster than Python setup
+- Initial data science/analytics - histograms, tabular output, basic aggregations
+- Polars plugin for large datasets - DataFrames without Python overhead
+
+**Use Bash only when:** bash-specific tooling, MCP unavailable, or bash-syntax integrations.
+
+## Reference Files
+
+Read the relevant file(s) based on what you need:
+
+| File | Read when you need... |
+|------|-----------------------|
+| [commands.md](references/commands.md) | Command reference tables (filters, strings, conversions, filesystem, math, dates) |
+| [types-and-syntax.md](references/types-and-syntax.md) | Type system, string types, operators, variables, control flow, cell-paths |
+| [data-analysis.md](references/data-analysis.md) | Format conversion, HTTP, Polars, SQLite, aggregation patterns |
+| [advanced.md](references/advanced.md) | Custom commands, modules, error handling, jobs, external commands, env config |
+| [bash-equivalents.md](references/bash-equivalents.md) | Complete Bash-to-Nushell translation table |
+| [http-transport.md](references/http-transport.md) | Differences when using HTTP transport instead of stdio |
+
+## MCP Server Quick Notes
+
+- `mcp__nushell__evaluate` - run code; `mcp__nushell__list_commands` - discover; `mcp__nushell__command_help` - help
+- State persists between calls. `$history` stores prior results (access `$history.0`, etc.)
+- Use `| to text` or `| to json` for large outputs. Use `ansi strip` for color removal.

skills/nushell/references/advanced.md

@@ -0,0 +1,164 @@
+# Nushell Advanced Patterns
+
+## Custom Commands with Full Signatures
+
+```nu
+def search [
+    pattern: string           # required positional
+    path?: string             # optional positional
+    --case-sensitive(-c)      # boolean flag (defaults false)
+    --max-depth(-d): int      # flag with value
+    ...extra: string          # rest params
+]: nothing -> list<string> {
+    # implementation
+}
+```
+
+### Pipeline Input/Output Types
+```nu
+def "str stats" []: string -> record {
+    let input = $in
+    {length: ($input | str length), words: ($input | split words | length)}
+}
+
+# Multiple input types
+def process []: [string -> record, list -> table] { ... }
+```
+
+### Environment-Modifying Commands
+```nu
+def --env goto [dir: string] {
+    cd $dir
+    $env.LAST_DIR = (pwd)
+}
+```
+
+### Wrapped External Commands
+```nu
+def --wrapped mygrep [...rest] {
+    ^grep --color=always ...$rest
+}
+```
+
+## Modules
+
+```nu
+module utils {
+    export def double [x: number] { $x * 2 }
+    export def triple [x: number] { $x * 3 }
+    export-env { $env.UTILS_LOADED = true }
+}
+
+use utils double         # import specific command
+use utils *              # import all exports
+use utils []             # import only environment
+```
+
+## Generate (Stateful Sequences)
+
+Closure comes first, initial value second. Returns `{out: value, next: state}`. Omit `next` to stop.
+
+```nu
+# Fibonacci
+generate {|fib| {out: $fib.0, next: [$fib.1, ($fib.0 + $fib.1)]}} [0, 1] | first 10
+
+# Counter
+generate {|i| if $i <= 5 { {out: $i, next: ($i + 1)} }} 0
+
+# With input stream (two-arg closure)
+1..5 | generate {|e, sum=0| let sum = $e + $sum; {out: $sum, next: $sum}}
+```
+
+## Functional Alternatives to Mutable State
+
+```nu
+# Instead of: mut sum = 0; for x in list { $sum += $x }
+[1 2 3 4 5] | reduce {|it, acc| $acc + $it}
+
+# With initial value
+[2 3 4 5] | reduce --fold 1 {|it, acc| $acc * $it}
+
+# Instead of: mut results = []; for x in list { $results = ($results | append (f $x)) }
+$list | each {|x| process $x}
+
+# Instead of: while with mutation
+generate {|state| if $state.done { null } else { {out: $state.val, next: (advance $state)} }} $initial
+```
+
+## Error Handling
+
+```nu
+# Basic try/catch
+try { open nonexistent.json } catch {|e| $"Failed: ($e.msg)" }
+
+# With finally (v0.111.0+)
+try { do-work } catch {|e| log-error $e.msg } finally { cleanup }
+
+# Custom errors
+error make {msg: "Value must be non-negative"}
+error make {msg: "Bad value", label: {text: "here", span: (metadata $value).span}}
+```
+
+## External Commands
+
+```nu
+^external_cmd args              # explicit external invocation
+ls | to text | ^grep pattern    # pipe structured data to external
+^cmd arg1 arg2 o+e>| str trim  # capture stdout+stderr
+^cmd | complete                 # get {exit_code, stdout, stderr} record
+$env.LAST_EXIT_CODE             # check last exit code
+
+# External output to structured data
+^git log --oneline -5 | lines | parse "{hash} {message}"
+
+# Pipe structured data to external
+{data: "value"} | to json | ^curl -X POST -d @- https://api.example.com
+```
+
+## Background Jobs
+
+```nu
+job spawn { long_running_cmd }                    # returns job ID
+job spawn --tag "server" { uvicorn main:app }     # with description
+job list                                          # list running jobs
+job kill $id                                      # terminate job
+
+# Getting results back via mailbox (main thread = job 0)
+job spawn { expensive_calc | job send 0 }; job recv
+job spawn { cmd | job send 0 --tag 1 }; job recv --tag 1  # filtered
+job recv --timeout 5sec                           # with timeout
+```
+
+**Key rules:** `job recv` reads from current job's mailbox only (no job ID arg). Background jobs send to main with `job send 0`. Use `--tag` for filtering.
+
+## Environment & Configuration
+
+```nu
+$env.PATH                      # PATH (list with ENV_CONVERSIONS, string otherwise)
+$env.Path                      # PATH on Windows
+$env.PATH = ($env.PATH | append "/new/path")
+$env.MY_VAR = "value"
+$env.MY_VAR? | default "fallback"  # safe access with default
+hide-env MY_VAR                # unset variable
+
+# Configuration
+$env.config.show_banner = false    # set individual config values
+$nu.default-config-dir             # config directory path
+$nu.home-dir                       # home directory
+config nu                          # edit config in $EDITOR
+```
+
+## Using nu -c from Bash
+
+```bash
+# Simple command
+nu -c 'ls | where size > 1mb | to json'
+
+# String interpolation (outer single quotes to avoid $ conflicts)
+nu -c 'let x = 42; $"answer: ($x)"'
+
+# Multi-statement
+nu -c 'let data = (open file.json); $data | get field'
+```
+
+Use single quotes for the outer wrapper since Nushell uses `$` for variables.

skills/nushell/references/bash-equivalents.md

@@ -0,0 +1,118 @@
+# Bash to Nushell Translation
+
+## File and Directory Operations
+
+| Bash | Nushell |
+|------|---------|
+| `ls` | `ls` |
+| `ls -la` | `ls --long --all` or `ls -la` |
+| `ls -d */` | `ls \| where type == dir` |
+| `find . -name "*.rs"` | `glob **/*.rs` or `ls **/*.rs` |
+| `mkdir -p path` | `mkdir path` (creates parents automatically) |
+| `touch file` | `touch file` |
+| `cp src dst` | `cp src dst` |
+| `cp -r src dst` | `cp -r src dst` |
+| `mv old new` | `mv old new` |
+| `rm file` | `rm file` |
+| `rm -rf dir` | `rm -r dir` |
+| `cat file` | `open --raw file` |
+| `head -5 file` | `open --raw file \| lines \| first 5` |
+| `tail -5 file` | `open --raw file \| lines \| last 5` |
+| `wc -l file` | `open --raw file \| lines \| length` |
+
+## Output Redirection
+
+| Bash | Nushell |
+|------|---------|
+| `> file` | `o> file` or `\| save file` |
+| `>> file` | `o>> file` or `\| save --append file` |
+| `> /dev/null` | `\| ignore` |
+| `> /dev/null 2>&1` | `o+e>\| ignore` |
+| `2>&1` | `o+e>\| ...` |
+| `cmd \| tee log \| cmd2` | `cmd \| tee { save log } \| cmd2` |
+
+## Text Processing
+
+| Bash | Nushell |
+|------|---------|
+| `grep pattern` | `where $it =~ pattern` or `find pattern` |
+| `grep -r pattern .` | `open --raw file \| lines \| where $it =~ pattern` |
+| `sed 's/old/new/'` | `str replace 'old' 'new'` |
+| `sed 's/old/new/g'` | `str replace --all 'old' 'new'` |
+| `awk '{print $1}'` | `split column ' ' \| get column0` |
+| `sort` | `sort` |
+| `sort -u` | `sort \| uniq` |
+| `uniq` | `uniq` |
+| `cut -d: -f1` | `split column ':' \| get column0` |
+| `tr '[:upper:]' '[:lower:]'` | `str downcase` |
+
+## Variables and Environment
+
+| Bash | Nushell |
+|------|---------|
+| `VAR=value` | `let var = "value"` |
+| `export VAR=value` | `$env.VAR = "value"` |
+| `echo $VAR` | `$env.VAR` |
+| `echo $HOME` | `$env.HOME` |
+| `echo $PATH` | `$env.PATH` (list on macOS/Linux) |
+| `echo $?` | `$env.LAST_EXIT_CODE` |
+| `unset VAR` | `hide-env VAR` |
+| `${VAR:-default}` | `$env.VAR? \| default "value"` |
+| `export PATH=$PATH:/new` | `$env.PATH = ($env.PATH \| append "/new")` |
+| `FOO=bar cmd` | `FOO=bar cmd` (same syntax) |
+
+## Command Execution
+
+| Bash | Nushell |
+|------|---------|
+| `cmd1 && cmd2` | `cmd1; cmd2` |
+| `cmd1 \|\| cmd2` | `try { cmd1 } catch { cmd2 }` |
+| `$(command)` | `(command)` |
+| `` `command` `` | `(command)` |
+| `command &` | `job spawn { command }` |
+| `jobs` | `job list` |
+| `kill %1` | `job kill $id` |
+| `type cmd` | `which cmd` |
+| `man cmd` | `help cmd` |
+| `bash -c 'code'` | `nu -c 'code'` |
+| `source script.sh` | `source script.nu` |
+
+## Control Flow
+
+| Bash | Nushell |
+|------|---------|
+| `if [ cond ]; then ... fi` | `if $cond { ... }` |
+| `[ -f file ]` | `"file" \| path exists` |
+| `[ -d dir ]` | `("dir" \| path exists) and ("dir" \| path type) == "dir"` |
+| `for f in *.md; do echo $f; done` | `ls *.md \| each { $in.name }` |
+| `for i in $(seq 1 10); do ...; done` | `for i in 1..10 { ... }` |
+| `while read line; do ...; done < file` | `open file \| lines \| each {\|line\| ... }` |
+| `case $x in ... esac` | `match $x { pattern => result, ... }` |
+
+## Pipes and Subshells
+
+| Bash | Nushell |
+|------|---------|
+| `cmd \| head -5` | `cmd \| first 5` |
+| `cmd \| tail -5` | `cmd \| last 5` |
+| `\` (line continuation) | `(` wrap in parens `)` |
+| `read var` | `let var = (input)` |
+| `read -s secret` | `let secret = (input -s)` |
+
+## History
+
+| Bash | Nushell |
+|------|---------|
+| `!!` | `!!` (inserts, doesn't execute) |
+| `!$` | `!$` |
+| `Ctrl+R` | `Ctrl+R` |
+
+## Key Behavioral Differences
+
+1. **Structured vs text**: Nushell pipelines pass tables/records, not text streams
+2. **Immutable by default**: `let` is immutable; use `mut` when needed
+3. **No word splitting**: Nushell doesn't split variables on whitespace
+4. **No glob expansion in variables**: Globs only expand in command position
+5. **Static parsing**: Code is parsed before execution; no `eval` equivalent
+6. **Implicit return**: Last expression is the return value; no `echo` needed
+7. **`>` is comparison**: Use `o>` or `save` for file redirection