home / skills / bdambrosio / cognitive_workbench / fs-head

fs-head skill

safe

This skill reads the first N lines of a text file from the filesystem sandbox to help you preview logs and configs quickly.

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

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

Files (2)

Skill.md

581 B

---
name: fs-head
type: python
description: "Read the first N lines of a text file under scenarios/<world_name>/fs."
schema_hint: {"path": "string (relative)", "lines": "int"}
---

# fs-head

Return the first N lines of a text file from the filesystem sandbox.

## Input

- `path`: Relative path under `scenarios/<world_name>/fs` (required)
- `lines`: Number of lines to return (default: 20)

## Output

Success returns:
- `resource_id`: Note ID containing the head slice and metadata

## Examples

```json
{"type":"fs-head","path":"logs/app.log","lines":50,"out":"$log_head"}
```

Overview

This skill reads the first N lines of a text file located in the sandbox filesystem under scenarios/<world_name>/fs. It returns a small, shareable note resource containing the requested head slice and basic metadata. Use it to quickly inspect logs, config snippets, or other text artifacts without loading entire files.

How this skill works

Provide a relative path under scenarios/<world_name>/fs and an optional lines count (default 20). The skill opens the target file, reads up to the requested number of lines from the start, and creates a note resource containing the slice and metadata such as source path and actual lines returned. On success it returns a resource_id referencing the stored head content.

When to use it

Previewing large log files to find recent startup messages or errors.
Inspecting the beginning of configuration files or generated outputs.
Verifying that a file exists and contains expected header lines.
Collecting a short snippet for debugging or sharing without exposing entire file contents.
Automated checks that require only file head samples.

Best practices

Always pass a relative path under scenarios/<world_name>/fs; absolute paths are not supported.
Set lines to a conservative number (for example 50) to avoid large outputs.
Use meaningful paths and keep filenames consistent to simplify scripted calls.
Handle the returned resource_id by retrieving or storing it securely if you need persistence.
Check for file existence and read permissions before calling to reduce error cases.

Example use cases

Read the first 50 lines of logs/app.log to look for startup errors.
Preview the head of config/settings.yml after a deployment to confirm headers.
Fetch the first 20 lines of an output file generated by a test scenario for quick validation.
Extract a header snippet to include in a bug report without attaching the full file.

FAQ

What path format should I use?

Use a relative path under scenarios/<world_name>/fs, for example logs/app.log.

What happens if the file has fewer lines than requested?

The skill returns all available lines and notes the actual number returned in the metadata.