How to use the Terminal Tools Foundations agent skill

What is an agent skill, and what does this one change?

An agent skill is a folder containing a SKILL.md file with instructions the agent loads when a task matches its description. This skill is required only when the terminal_* tools are available, and it does not add any tools of its own.

Once it is loaded, the agent knows how to run commands through terminal_exec, wait for long-running commands by polling their logs, and read the structured result fields. It also knows to check semantic_status before exit_code, so a normal outcome such as grep finding no matches is not misread as a failure.

• Runs shell commands and reads the shell_kind that executed them
• Moves commands that pass about 30 seconds into background jobs and polls their logs
• Pages through truncated output with output handles
• Chooses between read, edit, search and terminal file tools
• Pauses to check when a destructive warning appears

How do you install the Terminal Tools Foundations skill?

Download the skill ZIP from this page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with natural requests?

You do not need to name the skill. The agent loads it when a request involves running commands, builds, tests, scripts or long-running processes with the terminal tools. Plain requests in your project are enough.

Be specific about the working folder if it matters, because terminal and coding file tools default to the session workdir unless an absolute path is given.

• Run the test suite and tell me which tests fail.
• Start the production build in the background and check its logs every minute.
• Search the repo for every call to parse_config and list the files.
• Cancel the migration job that is still running.

What does a typical run look like?

A short command returns its result inline. If a command runs longer than the promotion threshold, the result arrives with auto_backgrounded set to true and a job_id. The agent then polls with terminal_job_logs until the job reports exited.

Large outputs are truncated inline. When stdout_truncated_bytes or stderr_truncated_bytes is above zero, the agent retrieves the rest with terminal_output_get and follows next_offset until eof.

• Check semantic_status first, then exit_code only when the exact number matters
• Track stdout and stderr offsets separately when polling
• Retained output handles last 5 minutes, so fetch promptly

What are the safety notes for scripts and network use?

This skill runs scripts: yes. It does not use the network itself. Every command the agent runs executes with your local permissions, so review what you ask it to do, especially with commands that delete files or change remote systems.

When a destructive warning appears in a result, for example for rm -rf, git push --force, git reset --hard, DROP TABLE, kubectl delete or terraform destroy, the command has already run. Stop and confirm that the action was intended before later steps depend on it.

Foreground commands use a deadline of 60 seconds by default, and jobs do not survive a restart of the terminal server.

What do you need before the skill works?

The skill assumes the terminal tools exist. Without them, its instructions do not apply. On POSIX systems the skill uses bash, not zsh, even on macOS. On Windows the shell is chosen in the order Git Bash, PowerShell, then cmd.

• Hive agent runtime with terminal_* tools enabled
• Bash on POSIX systems
• On Windows: Git Bash, PowerShell, or cmd
• Advanced category needed for explicit job creation and PTY sessions

What tips help the agent use terminal tools well?

Ask the agent to redirect full build logs to a file, then inspect that file along with the exit status. Output in the process ring can be overwritten, so a saved file is more reliable than memory for long builds.

Use managed jobs for anything that must run longer than a foreground call allows, and use signal_term to cancel one that should stop.

• Redirect complete build logs to a file for long builds
• Use search_tools to see which tools are loaded before assuming a capability exists
• Expect grep with no matches to return semantic_status ok with exit code 1