Fs Search Skill

FS Search Tool

Search the filesystem: list directories, glob pattern match files, or grep file contents. Uses the workspace-contained native filesystem backend.

Path sandbox: all paths resolve inside the per-workflow workspace root. Use workspace-relative paths; .. and ~ segments are rejected, and absolute paths are remapped into the workspace.

fs_search Tool

Schema Fields

Examples

List directory:

jsonCopy code
{"mode": "ls", "path": "/path/to/project"}

Find Python files:

jsonCopy code
{"mode": "glob", "path": ".", "pattern": "**/*.py"}

Search for a function:

jsonCopy code
{"mode": "grep", "path": ".", "pattern": "def my_function"}

Find all config files:

jsonCopy code
{"mode": "glob", "path": "/etc", "pattern": "*.conf"}

Response Format

ls mode:

jsonCopy code
{
  "path": "/",
  "entries": [
    {
      "path": "/src/",
      "is_dir": true,
      "size": 0,
      "modified_at": "2026-07-24T10:30:00"
    },
    {
      "path": "/README.md",
      "is_dir": false,
      "size": 1234,
      "modified_at": "2026-07-24T10:31:00"
    }
  ],
  "count": 2
}

glob mode:

jsonCopy code
{
  "path": "/",
  "pattern": "**/*.py",
  "matches": [
    {
      "path": "/src/main.py",
      "is_dir": false,
      "size": 1200,
      "modified_at": "2026-07-24T10:31:00"
    },
    {
      "path": "/tests/test_main.py",
      "is_dir": false,
      "size": 850,
      "modified_at": "2026-07-24T10:32:00"
    }
  ],
  "count": 2
}

grep mode:

jsonCopy code
{
  "path": "/",
  "pattern": "def main",
  "matches": [
    {"path": "/src/main.py", "line": 42, "text": "def main():"}
  ],
  "count": 1
}

path values in entries and matches are normalized virtual paths rooted at the workflow workspace. size and modified_at are best-effort metadata and may be absent if the backend cannot stat an entry.

Guidelines

1. Use ls to explore directory structure
2. Use glob to find files by name pattern (supports ** recursive, * wildcard, ? single char)
3. Use grep to search file contents (literal text, not regex)
4. Narrow a grep by choosing a more specific path; there is no file_filter parameter
5. The native backend does not impose a match-count cap; scope broad searches carefully because every matching result is returned