Shell Skill

Shell Tool

Execute short-lived shell commands in the workflow workspace. The backend uses Nushell when nu is installed. Otherwise it passes the command to the host shell (cmd.exe on Windows or the platform /bin/sh-style shell on POSIX). Shell-specific syntax is therefore conditional on the installed runner.

External binaries on PATH (npm, node, python, git, etc.) are available to whichever runner is selected.

For portable calls, prefer one external command with ordinary arguments, such as git status or python -V. Use file_read, file_modify, or fs_search for filesystem work; they avoid runner-specific parsing.

Runner-dependent syntax

The node rejects space-delimited && and || before selecting a runner, so those operators are unsupported even when the host shell would normally accept them. Prefer separate tool calls. If the environment is known to have Nushell, its equivalents include:

try { npm install } catch { print 'install failed'; exit 1 }
open README.md --raw | lines | first 20

Do not send Nushell pipelines, Bash substitutions, PowerShell cmdlets, or cmd.exe builtins unless the selected environment is known to support that syntax. GNU utilities such as sed, awk, and grep are not generally available on Windows.

shell_execute Tool

Schema

Response

{
  "stdout": "command output",
  "exit_code": 0,
  "truncated": false,
  "command": "ls"
}

Nushell reference (only when nu is installed)

Short-circuit "and-then" when Nushell is active

The node explicitly rejects the usual space-delimited && form. With Nushell available, use:

# Short-circuit using try/catch
try { npm install } catch { print 'install failed'; exit 1 }
ls -la

# Or inspect an external command's exit code
let r = (do { npm install } | complete)
if $r.exit_code == 0 { ls -la } else { print $r.stderr }

Common tasks when Nushell is active

Workspace and paths

• The cwd is the per-workflow workspace; relative paths resolve there.
• Filesystem operations elsewhere on this tool (read/write/edit via file_*) are workspace-contained and reject ../~ traversal. Shell execute() itself retains historical host-shell behavior and is not path-restricted, so prefer file_read / file_modify / fs_search for actual filesystem work.

Use the right tool

Guidelines

1. Never use && or ||. The node pre-flight rejects their common space-delimited forms before invoking either runner, and their behavior is not portable even without surrounding spaces.
2. Prefer one simple command per call. Chaining, variables, redirection, pipelines, and builtins depend on whether Nushell or the host shell was selected.
3. Use dedicated filesystem tools. file_read, file_modify, and fs_search are workspace-contained and avoid shell parsing differences.
4. Treat Nushell syntax as conditional. The reference above applies only when nu is installed.
5. Short-lived only. shell_execute always awaits completion — a small timeout does not make it run in the background, it just kills the command after N seconds. If the command runs longer than ~30s, opens a port, watches files, or is described as "dev server / watcher / daemon" (npm run dev, vite, tsx watch, python -m http.server, ...), use process_manager instead. Trying to "fire and forget" with timeout=2 will kill the process the moment the port comes up.
6. The timeout range is 1–600 seconds. Use process_manager instead of raising it for persistent processes.