How to use the Filesystem Search Tools agent skill

What the skill makes the agent do

The skill teaches the agent to choose between three kinds of tools for file work. terminal_rg searches file contents using ripgrep and is gitignore-aware by default. terminal_glob finds files by name or glob pattern. For anything else, such as modification-date or size filters, directory listings, tree views, single-file stat output and disk usage, the agent uses terminal_exec with commands like find, ls, tree, stat and du.

The skill also explains common ripgrep flags, how to read truncated results, and when to stop and narrow a search instead of raising limits. Its main rule is to read this guidance before reaching for raw shell commands like grep or find.

Install the skill from the ZIP or the Claude apps

There are two ways to add the skill. For Claude Code, download the skill ZIP from the page, unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder to limit it to that project. For the Claude apps, upload the ZIP under Settings, then Capabilities, then Skills.

After installing, check that the skill folder contains SKILL.md and the references folder, which holds find_predicates.md and ripgrep_cheatsheet.md.

Check the requirements before you start

The skill only describes tools that must already exist in your runtime. You need the Hive terminal tools (terminal_rg, terminal_glob and terminal_exec) and the ripgrep (rg) executable. Hive's quickstart installs and verifies ripgrep. If it is missing or broken, you can repair it from the repository root with the ensure_ripgrep script.

uv is needed because the ripgrep repair script runs through it. If ripgrep is installed in a non-standard location, set HIVE_RIPGREP_PATH to its absolute path.

• ripgrep (rg) executable, installed by the Hive quickstart or scripts/ensure_ripgrep.py
• HIVE_RIPGREP_PATH, optional, points to a custom binary
• Hive terminal tools: terminal_rg, terminal_glob, terminal_exec
• uv, used by the ripgrep repair script

How to trigger the skill with natural requests

You do not need special syntax. Ask for a file task in plain language, and the agent should follow the skill when the task involves searching or listing files. Be specific about the place to look, because the skill's choice of tool depends on whether you want file contents, a file name, or metadata such as age or size.

Requests that match the skill's categories include content searches, name lookups, and metadata filters. Check the agent's tool calls to confirm which tool it used.

• Search this project for TODO comments in Python files.
• Find the YAML config files under /etc.
• Show me the errors in /var/log from the last 30 minutes.
• Find log files larger than 100 MB under /var/log.
• Show a two-level tree of this repository.

Common search examples

The skill's examples show the structured calls the agent is expected to make. Content searches use terminal_rg, name lookups use terminal_glob, and predicate queries use terminal_exec with find. The ripgrep cheatsheet lists more flags for cases the structured wrapper does not cover, and you pass those through extra_args.

• Log search: terminal_rg with ignore_case=True and context=2 on /var/log.
• Hidden files: terminal_rg with hidden=True to include dotfiles.
• Gitignored files: terminal_rg with no_ignore=True to search files git would skip.
• Name lookup: terminal_glob with pattern="*.yaml" on /etc.

Safety notes for scripts and file access

The skill runs scripts and includes a ripgrep repair script, so review it before installing if your environment is restricted. It does not use the network. The main risk is what the agent reads. Searching a home folder or system configuration can expose secrets such as API keys, so decide which paths the agent may search.

If ripgrep is missing, terminal_rg returns an error by default. You can opt into an approximate search with allow_fallback=True, but that search ignores .gitignore and can miss files. Do not use it for an exhaustive inventory.

• Review the scripts before installing.
• Limit searches to the directories the task needs.
• Be careful with ~ and /etc, since they can contain secrets.
• Use the approximate fallback only when you accept incomplete results.

Tips for reliable results

If results are truncated, the skill says to narrow the pattern or path instead of raising limits. For terminal_glob, the default cap is 1000 results. If terminal_glob returns timed_out: true, it gives partial results, so narrow the search and run it again.

Note that ripgrep does not search inside archives. Extract an archive first, then search the extracted folder. The skill's description mentions archive contents, but the rg guidance in the source says to extract first.

• Use type_filter for file types, such as py, instead of glob patterns when possible.
• Use terminal_glob with a bare name like lk_scan_post_reactors to find a file anywhere under a folder.
• Check truncated and timed_out before treating results as complete.