shell-error-debug-workflow
Systematic workflow for diagnosing and resolving unknown errors from run_shell commands
- License 许可
- MIT
- 所属仓库
- HKUDS/AgentPilot
- 最近更新
- 2026-11-12
- Stars
- ★ 8.0k
- Forks
- 944
01 前言 Front Matter
- name
- shell-error-debug-workflow
- description
- Systematic workflow for diagnosing and resolving unknown errors from run_shell commands
02 资源文件 1
- 其他.skill_id40 B
03 SKILL.md 正文
Shell Error Debug Workflow
When run_shell returns an 'unknown error' or ambiguous failure, apply this systematic troubleshooting workflow to diagnose and resolve the issue.
When to Use This Skill
run_shellreturns an 'unknown error' message- Shell command fails without clear error output
- Command works locally but fails in the agent environment
- Intermittent or unexplained shell failures
Step-by-Step Troubleshooting Workflow
Step 1: Capture Explicit Stderr
Redirect stderr to stdout to capture all error output:
# Instead of:
run_shell command="some-command"
# Use:
run_shell command="some-command 2>&1"
This ensures error messages are captured in the output rather than being lost.
Step 2: Verify Working Directory
Confirm the current working directory and its contents:
run_shell command="pwd && ls -la"
Check that:
- You're in the expected directory
- Required files/directories exist
- Permissions are correct
Step 3: Check Tool/Command Availability
Verify the required command or tool exists and is accessible:
run_shell command="which some-command || command -v some-command || type some-command"
If the tool is not found, check PATH or install the required package.
Step 4: Use Absolute Paths
Replace relative paths with absolute paths to avoid directory-related issues:
# Instead of:
run_shell command="python script.py"
# Use:
run_shell command="$(pwd)/script.py"
# or
run_shell command="/absolute/path/to/script.py"
Step 5: Test with Minimal Command
Isolate the issue by running a minimal version of the command:
# Test basic functionality first
run_shell command="echo 'test'"
# Then gradually add complexity
run_shell command="some-command --version"
run_shell command="some-command --help"
Step 6: Check Environment Variables
Some commands depend on specific environment variables:
run_shell command="env | grep -i relevant_var"
Complete Diagnostic Sequence
For persistent unknown errors, run this complete diagnostic:
# 1. Capture full environment
run_shell command="pwd && echo '---' && ls -la && echo '---' && env"
# 2. Test command with full error capture
run_shell command="your-command 2>&1 | head -50"
# 3. Check command availability
run_shell command="which your-command || echo 'Command not found in PATH'"
# 4. Try with absolute path
run_shell command="/full/path/to/your-command 2>&1"
Common Causes and Solutions
| Symptom | Likely Cause | Solution |
|---|---|---|
| No output, unknown error | stderr not captured | Add 2>&1 to command |
| File not found | Wrong working directory | Use pwd to verify, use absolute paths |
| Permission denied | File/directory permissions | Check with ls -la, adjust permissions |
| Command not found | Tool not installed or not in PATH | Use which to check, install or specify full path |
| Intermittent failures | Race conditions or timing | Add delays, check for file locks |
Example: Troubleshooting a Python Script Failure
# Initial failing command
run_shell command="python process.py"
# Returns: unknown error
# Apply diagnostic workflow:
# Step 1: Capture stderr
run_shell command="python process.py 2>&1"
# Step 2: Verify directory
run_shell command="pwd && ls -la"
# Step 3: Check Python availability
run_shell command="which python && python --version"
# Step 4: Use absolute path
run_shell command="$(pwd)/process.py 2>&1"
# or
run_shell command="/usr/bin/python3 $(pwd)/process.py 2>&1"
Best Practices
- Always capture stderr when debugging:
2>&1 - Verify assumptions about working directory and file locations
- Start simple before running complex commands
- Use absolute paths in production/repeatable scripts
- Check tool versions when behavior seems inconsistent
- Document environment when errors are hard to reproduce
When to Escalate
If this workflow does not resolve the issue:
- The error may be environmental (container/runtime specific)
- Consider using
shell_agentfor complex shell tasks that require autonomous error handling - Check for resource constraints (disk space, memory, timeouts)
04 同仓库更多 Skills
agentpilot
Set up AgentPilot and use its single entry to prepare missing inputs and run configured RSI experiments. Use when the user requests AgentPilot installation or work with AgentPilot.
remember
Review auto-memory entries and propose promotions to OPENSPACE.md, OPENSPACE.local.md, or retained auto-memory topics; detect duplicates, stale facts, conflicts, and ambiguous entries before making changes.
skill-discovery
Search reusable OpenSpace skills locally, and browse cloud packages step by step when a cloud skill may help. Reusing proven skills saves tokens, improves reliability, and extends your capabilities beyond built-in tools.
delegate-task
Delegate tasks to OpenSpace — a full-stack autonomous worker for coding, DevOps, web research, and desktop automation, backed by an extensive MCP tool and skill library. Skills auto-improve through use, reducing token consumption over time. A cloud community lets agents share and collectively evolve reusable skills.
write-special-chars-ts-check
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.
write-special-chars-readback
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of /tmp helper scripts.