Purpose

Run read-only shell commands to diagnose and document the current system state — tool versions, environment variables, running processes, open ports, file permissions, disk and memory usage, and network connectivity. Produce a structured report that downstream agents can use to validate prerequisites or troubleshoot failures.

When to use

• A build or test failure may be caused by environment misconfiguration.
• A new developer needs to verify their local setup matches project requirements.
• An agent needs to confirm runtime prerequisites before executing a plan.
• Debugging a "works on my machine" discrepancy between environments.
• Pre-deployment verification of server state.

Do NOT use when

• The task requires installing packages or modifying system configuration — hand off to a setup skill.
• The investigation is purely about source code, not the runtime environment — use

  repo-evidence-gathering

  .
• The user needs a security audit — use

  security-review

  for that scope.
• The system is remote and requires SSH — this skill operates on the local shell only.

Operating procedure

1. Run

   uname -a

   and

   cat /etc/os-release 2>/dev/null || sw_vers 2>/dev/null

   to identify the OS and kernel version.
2. Check required tool versions by running

   node --version

   ,

   python3 --version

   ,

   go version

   ,

   rustc --version

   ,

   java -version

   ,

   docker --version

   ,

   git --version

   — skip tools that return "command not found" and note them as missing.
3. Run

   env | grep -iE 'PATH|HOME|NODE_ENV|PYTHON|RUST|GOPATH|JAVA_HOME|DATABASE_URL|PORT|API' | sort

   to capture relevant environment variables (redact any values containing "secret", "key", "token", or "password").
4. Check running processes with

   ps aux --no-headers | grep -iE 'node|python|java|docker|postgres|redis|nginx|mysql' | head -20

   to identify active services.
5. Inspect open ports with

   ss -tlnp 2>/dev/null || netstat -tlnp 2>/dev/null

   and list listening ports with their associated PIDs.
6. Check disk usage with

   df -h /

   and memory with

   free -h 2>/dev/null || vm_stat 2>/dev/null

   — flag if disk is above 90% or available memory is below 500MB.
7. Verify file permissions on key project files: run

   ls -la

   on the repo root, any

   .env

   files, and config directories — flag world-readable secrets files.
8. Test network connectivity by running

   curl -sS -o /dev/null -w '%{http_code}' https://registry.npmjs.org/ 2>/dev/null

   (or equivalent) for package registries the project depends on.
9. Check for Docker state if applicable: run

   docker ps --format 'table {{.Names}}	{{.Status}}	{{.Ports}}'

   and

   docker compose ps 2>/dev/null

   .
10. Compile all results into the output format below, marking each check as PASS, WARN, or FAIL.

Decision rules

• Never run commands that modify state — no

  rm

  ,

  mv

  ,

  install

  ,

  write

  , or

  stop

  .
• Redact any environment variable value that looks like a credential (contains key, secret, token, password).
• If a command times out after 10 seconds, mark it as TIMEOUT and move on.
• Report exact version strings, not just "installed" — downstream agents need precise versions.
• When a check fails, include the raw command output so the user can diagnose further.

Output requirements

1. System Info — OS, kernel, architecture.
2. Tool Versions Table —

   | Tool | Version | Status (OK/Missing/Wrong) |

3. Environment Variables — relevant vars with redacted secrets.
4. Running Services — active processes relevant to the project.
5. Port Map —

   | Port | PID | Process | Protocol |

6. Resource Status — disk and memory usage with PASS/WARN/FAIL.
7. Permission Flags — any files with insecure permissions.
8. Network Connectivity — registry reachability results.
9. Overall Readiness — READY / NOT READY with list of blockers.

References

• Project README or AGENTS.md for expected tool versions

• package.json

  engines field,

  .tool-versions

  ,

  .nvmrc

  ,

  rust-toolchain.toml

• Docker Compose files for expected service dependencies

Related skills

• repo-evidence-gathering

  — complements shell inspection with source-level evidence

• security-review

  — uses permission and environment findings for security assessment

• ticket-creator

  — converts environment issues into setup tickets

• api-debugging

  — may follow shell-inspection when debugging service connectivity

Failure handling

• If a command is not available on the current OS, skip it and note the OS limitation.
• If permission is denied for a check, log the command and error, mark as DENIED, and continue.
• If the environment has no project context (empty directory), report "no project detected" and list only system-level findings.
• If more than 5 checks return FAIL, add a prominent banner: "Environment has critical issues — resolve before proceeding."