home / skills / bdambrosio / cognitive_workbench / fs-find

fs-find skill

This skill finds files by glob pattern under scenarios/<world_name>/fs and returns a structured collection of matching notes.

npx playbooks add skill bdambrosio/cognitive_workbench --skill fs-find

Review the files below or copy the command above to add this skill to your agents.

Files (2)

Skill.md

1.4 KB

---
name: fs-find
type: python
description: "Find files by filename pattern (glob) under scenarios/<world_name>/fs and return a Collection."
schema_hint: {"pattern": "string (glob pattern)", "path": "string (relative)", "recursive": "bool", "max_results": "int"}
---

# fs-find

Find files by filename pattern (glob) within the filesystem sandbox for the current world.

## Input

- `pattern`: Glob pattern for filename matching (required, e.g., "*.txt", "Nan_*", "*Ar*")
- `path`: Directory to search (default: "." root)
- `recursive`: Whether to search subdirectories (default: true)
- `max_results`: Maximum files to return (default: 200)

## Pattern Matching

- Uses shell-style glob patterns (via Python `fnmatch`)
- Matches against **filename only** (not full path)
- Common patterns:
  - `"*.txt"` - all .txt files
  - `"Nan_*"` - files starting with "Nan_"
  - `"*Ar*"` - files containing "Ar"
  - `"Nan_Ar.txt"` - exact filename match

**Note:** Pattern cannot contain path separators (`/` or `\`). Use the `path` parameter to search in specific directories.

## Output

Success returns:
- `resource_id`: Collection ID containing matching file Notes
- Collection items are Notes (files) with same structure as `fs-list` file Notes

## Examples

```json
{"type":"fs-find","pattern":"*.txt","out":"$txt_files"}
{"type":"fs-find","pattern":"Nan_*","path":"bhagavan","recursive":false,"out":"$matches"}
{"type":"fs-find","pattern":"*Ar*","out":"$ar_files"}
```

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.

FAQ

Can the pattern match directory names or only files?

The skill matches filenames only (not full paths). It returns file Notes for filesystem files; directories are not matched as filenames.

Can I include path separators in the pattern?

No. Patterns cannot contain '/' or '\'. Use the path parameter to search within specific directories or subdirectories.

What happens if no files match?

The skill returns an empty Collection resource (no file Notes) and a valid resource_id indicating zero matches.