fs-stat skill

Overview

This skill returns metadata for a file or directory located under scenarios/<world_name>/fs in the sandboxed filesystem. It queries the specified relative path and produces a Note-style resource containing file attributes and timestamps. Use it to inspect files or directories before reads, writes, or sync operations.

How this skill works

You provide a relative path under scenarios/<world_name>/fs and the skill inspects that path in the sandbox. It gathers standard filesystem metadata (existence, type, size, timestamps, permissions where available) and returns a resource_id pointing to a Note that stores the collected metadata. Errors are returned when the path is missing or outside the allowed directory.

When to use it

• Check whether a file or directory exists before attempting to read or write.
• Gather size and timestamp information to decide if a file needs updating or syncing.
• Verify that a path refers to a file or a directory for conditional logic.
• Obtain permissions and metadata for logging, audit, or debugging purposes.
• Confirm sandboxed path validity from within scenario-driven workflows.

Best practices

• Always pass relative paths under scenarios/<world_name>/fs; absolute or parent paths are rejected.
• Handle error responses for non-existent paths to avoid unexpected failures.
• Use the returned resource_id to fetch or persist metadata in downstream steps.
• Avoid relying on platform-specific permission bits; treat permissions as advisory in the sandbox.
• Combine with file read/write steps to enforce pre-checks and minimize race conditions.

Example use cases

• Preflight check: confirm a config file exists and read its modification time before loading.
• Sync decision: compare remote and local file timestamps to decide whether to upload a file.
• Conditional processing: only process entries that are directories or files of a certain size.
• Audit logging: capture file metadata into a Note for traceability after pipeline steps.

FAQ