fs-find_skill

Overview

This skill finds files by filename pattern (glob) inside the sandboxed filesystem for the current world and returns the results as a Collection of file Notes. It searches under scenarios/<world_name>/fs and supports simple shell-style filename patterns. Results are returned as a Collection resource ID containing Notes with the same structure as fs-list file Notes.

How this skill works

You provide a filename pattern (shell-style glob) and an optional path, recursion flag, and maximum result count. The skill walks the specified directory (default "." under the world fs), matches filenames (not full paths) using fnmatch-style patterns, and stops when max_results is reached. Matching files are wrapped as Notes and returned inside a Collection with a resource_id.

When to use it

• Locate files by filename pattern without scanning full path strings.
• Collect a set of files for batch processing or inspection.
• Quickly enumerate files matching extensions or naming conventions (e.g., logs, reports, exports).
• Limit search scope to a subfolder while keeping filename-based matching.
• Prevent heavy scans by setting max_results for large repositories.

Best practices

• Always keep patterns free of path separators; use the path parameter to narrow directories.
• Prefer simple patterns ("*.txt", "prefix_*", "*token*") for predictable matches.
• Set recursive to false if you only want the specified directory level.
• Use max_results to bound work and avoid extremely large collections.
• Combine with other tools that accept Collection resource IDs to build pipelines.

Example use cases

• Find all text files in the world fs: pattern "*.txt" with default path and recursive true.
• Get files starting with a prefix in a specific folder: pattern "Nan_*" and path "bhagavan", recursive false.
• Collect files containing a substring in the name: pattern "*Ar*" across the world filesystem.
• Limit results when exploring: pattern "*.log" with max_results set to 50 to inspect recent logs.
• Feed matching files into processing steps that accept a Collection resource_id.