shell-and-output

name	shell-and-output
description	Use when running CLI commands in a harness WITHOUT reliable output capture — no built-in stdout/stderr or exit-code reporting. Not needed in Claude Code, whose shell tools already capture output and exit codes.
version	1.1.0
platform	{"os":"windows","shell":"pwsh","powershell_version":"7+"}
entrypoints	{"module":"scripts/ShellOutput.psm1","runner":"scripts/run-logged.ps1"}

Shell and Output (PowerShell 7+)

Applicability

This skill targets harnesses whose shell execution does NOT reliably return stdout/stderr and exit codes — custom runners, minimal agent loops, or wrappers that swallow output. If the harness's shell tool already reports output and exit codes deterministically — Claude Code's Bash and PowerShell tools do — this skill does not apply. Use the native tools directly; the logging protocol below would only add cost.

Purpose

Ensure all CLI work is deterministic and verifiable on Windows PowerShell 7+.

This skill exists to prevent false positives, silent failures, and ambiguous shell execution results.

Key principles:

• Never assume success from missing or empty output
• Always capture stdout and stderr to a log file
• Always verify exit codes and scan for failure indicators
• Avoid non-PowerShell tooling and syntax
• Avoid chaining meaningful commands

This skill is authoritative.

---

Preconditions

• PowerShell version: 7+
• Operating system: Windows
• Repository root is the current working directory unless otherwise stated

---

Hard Rules

1) No Silent Success

• Never conclude success from “no output” in the chat UI.
• All meaningful commands MUST use the output capture protocol.
• All meaningful shell commands MUST be executed via
  Invoke-LoggedCommand from scripts/ShellOutput.psm1.

Direct invocation of shell commands is prohibited.

---

2) Output Capture Protocol (Required)

Every meaningful command MUST:

1. Create ./temp if it does not exist
2. Redirect stdout and stderr to ./temp/<log>.txt
3. Wait briefly after execution
   • Default: 500ms
   • Increase for long-running or heavy commands
4. Read the log file contents
5. Evaluate:
   • Exit code
   • Failure pattern scan
6. Decide success or failure based on both
7. Summarize:
   • Command executed
   • Exit code
   • Log path
   • Key log lines (especially on failure)

---

3) Searching Rules

• Never use grep
• For command output logs, use Select-String
• For repository content searches:
  • Prefer the agent’s repository search tool
  • Avoid shell pipelines

---

4) No Tool Invocation Inside Shell Strings

• Shell command strings MUST NOT invoke other tools
• Tool usage must remain outside shell execution contexts

---

5) Quoting and Paths

• Always quote paths that may contain spaces
• Use Join-Path for path construction
• Use ./temp for all command logs

---

6) Command Chaining Policy (PowerShell 7.5.4)

• Do NOT chain meaningful commands
• Execute one meaningful command per invocation
• Each command MUST have its own dedicated log file

---

Required Outputs (Per Meaningful Command)

For every meaningful command, the agent MUST report:

• Command string executed
• Log file path
• Exit code
• Whether failure patterns were detected
• Short excerpt of relevant log lines
  (especially on failure)

---

PowerShell Implementation

• Import the module from this skill's own scripts/ directory (resolve the skill root from wherever this skill is installed):

  Import-Module "<skill-root>/shell-and-output/scripts/ShellOutput.psm1"
  

• Primary execution helper:

  • Invoke-LoggedCommand

• Assertion helper:

  • Assert-LoggedSuccess (fail fast on detected errors)

---

Enforcement

If any rule in this skill is violated:

• The command result is invalid
• The agent MUST stop and re-execute using the correct protocol
• Downstream reasoning based on invalid execution is prohibited

---

Intent

This skill exists to ensure:

• Deterministic shell behaviour
• Verifiable outcomes
• Reproducibility across agents and sessions
• Clear failure visibility

Correctness is more important than speed.