home / skills / bdambrosio / cognitive_workbench / fs-read

fs-read skill

safe

This skill reads text, JSON, or PDF files from the filesystem sandbox and returns a structured Note with content and metadata.

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

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

Files (2)

Skill.md

1.3 KB

---
name: fs-read
type: python
description: "Read a text, JSON, or PDF file under scenarios/<world_name>/fs and return a Note."
schema_hint: {"path": "string (relative)", "max_chars": "int", "as_json": "bool", "grobid_url": "string"}
---

# fs-read

Read a file from the filesystem sandbox and return its content as a Note. Supports text, JSON, and PDF files.

## Input

- `path`: Relative path under `scenarios/<world_name>/fs` (required)
- `max_chars`: Optional maximum characters to read (text and PDF files only)
- `as_json`: Force JSON parse (default: false, text files only)
- `grobid_url`: Optional GROBID server URL for enhanced PDF parsing (from world_config)

## File Types

- **Text files**: Read as plain text
- **JSON files**: Parsed and returned as structured data
- **PDF files**: Extracted using GROBID (if `grobid_url` provided) or pymupdf fallback. Returns text with PDF metadata (title, author, page count, etc.)

## Output

Success returns:
- `resource_id`: Note ID containing structured content and metadata

## Examples

```json
{"type":"fs-read","path":"notes/todo.txt","out":"$todo"}
{"type":"fs-read","path":"data/config.json","as_json":true,"out":"$config"}
{"type":"fs-read","path":"papers/article.pdf","out":"$paper"}
{"type":"fs-read","path":"papers/article.pdf","max_chars":5000,"out":"$paper_preview"}
```

Overview

This skill reads a file from the sandboxed filesystem under scenarios/<world_name>/fs and returns its content as a Note. It supports plain text, JSON, and PDF files and can optionally limit the read size or parse JSON. PDF extraction uses GROBID when available or a pymupdf fallback and includes basic PDF metadata in the result.

How this skill works

You provide a relative path under scenarios/<world_name>/fs and optional parameters: max_chars to limit text/PDF output, as_json to force JSON parsing of text files, and grobid_url to enable enhanced PDF extraction. The skill detects file type, parses JSON into structured data, extracts text from PDFs with metadata, or returns raw text. On success it creates and returns a Note resource ID containing the content and metadata.

When to use it

You need to inspect or extract content from a sandbox file during a scenario run.
You want structured JSON returned for configuration or data files.
You need to extract text and metadata from academic papers or reports in PDF form.
You want to preview a large document by limiting the number of characters returned.
You need an input Note for downstream agents or workflows that consume text or parsed JSON.

Best practices

Always provide a path relative to scenarios/<world_name>/fs to avoid permission errors.
Use max_chars to avoid returning very large documents when you only need a preview.
Set as_json=true for text files that contain valid JSON to get structured data.
Supply a grobid_url in world_config for higher-quality PDF extraction when available.
Handle the returned Note ID: fetch the Note if you need the full content or metadata programmatically.

Example use cases

Load a todo list or notes file (notes/todo.txt) and create a task summary Note.
Read a configuration JSON (data/config.json) and pass the parsed object to an agent.
Extract text and metadata from a research paper PDF (papers/article.pdf) for indexing.
Generate a short preview of a long PDF by setting max_chars for quick review.

FAQ

What file types are supported?

Plain text, JSON, and PDF files are supported. JSON files are parsed into structured data.

How do I limit the size of returned text?

Use the max_chars parameter for text and PDF extraction to limit the number of characters returned.

When should I provide grobid_url?

Provide grobid_url in world_config when you have access to a GROBID server for better PDF parsing; otherwise the skill uses pymupdf as a fallback.