Can I list paths outside scenarios/ /fs?

No. The path must be relative and confined to scenarios/ /fs for the current world.

home / skills / bdambrosio / cognitive_workbench / fs-list

fs-list skill

safe

This skill lists files and directories under scenarios/world_name/fs and returns a structured Collection for easy navigation.

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

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

Files (2)

Skill.md

976 B

---
name: fs-list
type: python
description: "List files and directories under scenarios/<world_name>/fs and return a Collection."
schema_hint: {"path": "string (relative)", "recursive": "bool", "include_files": "bool", "include_dirs": "bool", "max_entries": "int"}
---

# fs-list

List files and directories within the filesystem sandbox for the current world.

## Input

- `path`: Relative path under `scenarios/<world_name>/fs` (default: root)
- `recursive`: Whether to recurse into subdirectories (default: false)
- `include_files`: Include files (default: true)
- `include_dirs`: Include subdirectories as Collections (default: true)
- `max_entries`: Max entries created across recursion (default: 200)

## Output

Success returns:
- `resource_id`: Collection ID
- Collection items are Notes (files) and Collections (subdirectories)

## Examples

```json
{"type":"fs-list","path":".","out":"$root"}
{"type":"fs-list","path":"docs","recursive":true,"out":"$docs_tree"}
```

Overview

This skill lists files and directories under scenarios/<world_name>/fs and returns the results as a Collection. It produces Collection items where files become Notes and subdirectories become nested Collections. The output includes a resource_id referencing the created Collection for further use.

How this skill works

You provide a relative path under scenarios/<world_name>/fs and optional flags: recursive, include_files, include_dirs, and max_entries. The skill walks the specified directory (optionally recursively), converts files to Notes and directories to Collections, and stops when max_entries is reached. On success it returns a resource_id for the Collection containing the discovered items.

When to use it

Explore the sandbox filesystem for the current world.
Generate an index or inventory of files for automation or reporting.
Collect files and directories to pass into other agents or workflows.
Quickly verify presence and structure of scenario assets.
Create a manifest before packaging or testing a scenario.

Best practices

Use a focused relative path rather than listing the entire root when possible.
Set recursive=true only when you need full subtree scans to avoid large outputs.
Adjust max_entries to limit resource use and avoid excessively large Collections.
Toggle include_files/include_dirs to shape output for downstream consumers.
Handle the returned resource_id immediately to avoid orphaned Collections.

Example use cases

List the root sandbox: path='.' to get a top-level Collection of files and folders.
Index documentation: path='docs', recursive=true to build a full docs tree Collection.
Validate assets: check for existence of specific files before running a scenario.
Produce a compact directory listing by setting include_dirs=false to retrieve only files.
Create a nested Collection to feed another agent that processes file contents.

FAQ

Can I list paths outside scenarios/<world_name>/fs?

No. The path must be relative and confined to scenarios/<world_name>/fs for the current world.

What happens if the filesystem has more entries than max_entries?

The listing stops once max_entries entries are created. Increase max_entries or narrow the path/disable recursion to capture everything you need.