playbooks

home / skills / bdambrosio / cognitive_workbench / init

init skill

/src/world-tools/fs/init

This skill builds a filesystem catalog during initialization to inform planning with a structured view of directories, files, and documentation.

npx playbooks add skill bdambrosio/cognitive_workbench --skill init

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

Files (2)
Skill.md
2.0 KB
---
name: init
type: python
description: "Initialize filesystem world by building catalog for prompt context"
---

# Filesystem Initialization Tool

Automatically executed during executor initialization to build a filesystem catalog that provides the agent with awareness of available files and directories in the sandbox.

## Purpose

This tool scans the filesystem sandbox (`scenarios/<world_name>/fs/`) and creates a structured catalog that is automatically included in planner prompts. This gives the agent initial awareness of:
- Directory structure
- Available files and their types
- Directory documentation (if present)

## Behavior

1. **Lightweight Scan**: Performs a limited-depth scan (max depth 2) with entry limits (30 per directory) to avoid performance issues
2. **Directory Documentation**: Reads `Skill.md`, `README.md`, or `DIRECTORY.md` files in directories and includes summaries
3. **Format Detection**: Identifies file types (text, json, binary, pdf) from extensions and samples
4. **Catalog Storage**: Stores the catalog in `world_state['_prompt_sections']['filesystem_catalog']` for generic retrieval by the executor

## Automatic Execution

- This tool is automatically executed during executor initialization if present
- Tool name must be `init` or `<world_name>-init` (e.g., `fs-init`)
- Runs after full tool catalog is loaded
- Executes via `execute_action_with_log()` so it's logged and published

## Output

The catalog is formatted as text and includes:
- Root directory path
- Directory tree structure (limited depth)
- File listings with type and size
- Directory documentation summaries (where available)
- Note about using fs-* tools for detailed exploration

## Limitations

- Limited depth scan (max 2 levels) to control token cost
- Entry limits (30 per directory) to avoid overwhelming prompts
- Performance warning logged if directories exceed 30 entries

## Integration

The catalog is retrieved generically by `executor.get_world_prompt_context()` and included in planner prompts without any world-specific code in the core planner.

Overview

This skill initializes the sandbox filesystem by building a concise catalog used in planner prompts. It gives the agent immediate awareness of directory layout, available files, types, and any per-directory documentation summaries. The catalog is stored in world state for automatic retrieval during planning.

How this skill works

On initialization it performs a lightweight, limited-depth scan of the sandbox filesystem to collect a directory tree and file listings. It detects file types (text, JSON, binary, PDF) by extension and content sampling, reads common directory documentation files to produce short summaries, and records file sizes and basic metadata. The resulting text-formatted catalog is saved into the world prompt context so the planner can include it without extra world-specific code.

When to use it

  • Automatically runs during agent executor initialization when present in the world.
  • When you need the agent to know what files and directories exist before planning actions.
  • When you want quick context for large sandboxes without expensive deep scans.
  • When integrating new scenarios so the planner has immediate filesystem awareness.

Best practices

  • Keep sandbox directories well-organized so the catalog is informative and compact.
  • Add short documentation files in key directories to provide helpful summaries for the agent.
  • Avoid huge single directories; the tool limits entries per directory to preserve performance.
  • Rely on the catalog for initial awareness, then use dedicated fs-* exploration tools for deeper inspection.

Example use cases

  • Preloading file/directory context for a scenario-based agent so it can plan file operations safely.
  • Summarizing available datasets and config files before executing a pipeline orchestration plan.
  • Providing quick visibility of documentation and assets in a newly mounted sandbox during testing.
  • Preventing blind operations by exposing file types and sizes to the planner up front.

FAQ

What depth and entry limits does the scan use?

The scan is limited to two directory levels and caps entries per directory (default 30) to control token and performance costs.

Where is the catalog stored for the planner to use?

The generated text catalog is saved into the world state under the prompt sections for generic retrieval by the planner.

Will this replace focused file exploration tools?

No. This provides initial, lightweight awareness. Use targeted fs-* tools for detailed reads, edits, or deep traversal.