How to use the Terminal Tools Troubleshooting agent skill

What the skill makes the agent do

The skill is a set of diagnostic recipes. It is meant to be loaded on demand, not preloaded, because the foundational terminal-tools skill already covers normal behaviour. When a result looks wrong, the agent matches the symptom to a section and works through the likely causes and fixes listed there.

The symptoms it covers include empty stdout with no error, exit_code set to null, an output_handle that came back expired, errors such as "too many jobs", "session busy" and "PTY cap reached", a warning that was set unexpectedly, and a semantic_status that disagrees with exit_code.

• Empty stdout: checks stderr, output truncation via stdout_truncated_bytes, silent commands, pipe redirection and output buffering.
• exit_code null: distinguishes auto-backgrounded jobs, hard timeouts, pre-spawn failures and still-running jobs.
• Expired output_handle: explains the 5-minute TTL and the 64 MB store cap, and suggests re-running the command.
• Job and session limits: explains TERMINAL_TOOLS_MAX_JOBS (default 32) and TERMINAL_TOOLS_MAX_PTY (default 8) and how to free capacity.
• Warnings and semantic status: explains that a warning is informational and that semantic_status is more reliable than raw exit_code.

How to install the skill

Download the ZIP file for this skill from our page. Unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only to that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

How to trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent when to read it, so describe the surprising result in your own words. Mention the symptom, the tool, or the error text you saw.

The skill is meant to load only when something unexpected happens, so ask about the specific symptom rather than asking for general terminal help.

• "The terminal_pty_run call came back with exit_code null. What should I check?"
• "My output_handle says expired. Why, and how do I avoid it next time?"
• "I got a 'too many jobs' error from terminal_job_manage. How do I free up slots?"
• "stdout is empty but there was no error. Walk me through the troubleshooting steps."
• "The warning was set on my command even though it worked. Is that a problem?"

Examples of symptoms and what the agent does

Suppose a background command returns exit_code null with auto_backgrounded set to true and a job_id. The skill's table says this means the command was moved to the background, so the agent should follow the job with terminal_job_logs rather than treat it as a failure.

Suppose a grep returns semantic_status "ok" but exit_code 1. The skill explains that grep exits 1 when it finds no matches, so the agent should trust semantic_status and read semantic_message for the explanation.

What you need before using it

This skill does not work on its own. It refers to the terminal-tools foundational skill and its tool set, including terminal_pty_run, terminal_job_logs and terminal_job_manage, but it does not include those. Make sure the foundational skill and tools are available to the agent first.

The skill runs no scripts and uses no network access, according to its listing. It is a Markdown reference file (SKILL.md).

• The terminal-tools foundational skill and its tools
• A Claude app or Claude Code setup that loads skills from the folders above

Safety notes on scripts, network and review

The skill itself runs no scripts and makes no network calls. The commands it discusses are run by the terminal-tools interface, so the usual care applies to any command the agent runs.

The skill tells the agent that a warning means verify the side effect was intended before continuing. It is not suitable for setups where the agent runs commands unattended without review.

• Treat warnings such as those for rm -rf or git push --force as prompts to check intent.
• Keep a human in the loop when commands can change files or remote repositories.
• The skill notes that the shell is bash, so do not expect zsh behaviour in shell=True commands.

Tips for getting the most from it

Give the agent the exact error text and the full result envelope. The skill's recipes depend on fields such as stderr, stdout_truncated_bytes, timed_out and semantic_message.

Paginate large outputs early, since output handles expire after 5 minutes. For very large output, the skill points to terminal_job_* functions, which use a 4 MB ring buffer with offsets and no expiry.

Close idle PTY sessions with terminal_pty_close when you hit the PTY cap, because opening a new session fails once the cap is reached.