home / skills / bdambrosio / cognitive_workbench / fs-grep

fs-grep skill

safe

This skill searches text files under scenarios/<world_name>/fs for a regex pattern and returns matching snippets as notes.

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

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

Files (2)

Skill.md

988 B

---
name: fs-grep
type: python
description: "Search text files under scenarios/<world_name>/fs and return match snippets."
schema_hint: {"path": "string (relative)", "pattern": "string", "recursive": "bool", "max_matches": "int", "context": "int", "case_insensitive": "bool"}
---

# fs-grep

Search text files for a regex pattern and return match snippets as Notes.

## Input

- `path`: Relative path under `scenarios/<world_name>/fs` (default: root)
- `pattern`: Regex pattern to search for (required)
- `recursive`: Recurse into subdirectories (default: true)
- `max_matches`: Max matches to return (default: 20)
- `context`: Context lines before/after each match (default: 0)
- `case_insensitive`: Case-insensitive regex (default: false)

## Output

Success returns:
- `resource_id`: Collection ID of match Notes

## Examples

```json
{"type":"fs-grep","path":"src","pattern":"TODO","recursive":true,"out":"$todos"}
{"type":"fs-grep","pattern":"error","context":2,"out":"$errors"}
```

Overview

This skill searches text files under scenarios/<world_name>/fs for a regex pattern and returns matching snippets as Notes. It is designed to quickly surface code comments, errors, TODOs, or any text matches within a scenario filesystem. Results are returned as a collection resource you can reference in workflows.

How this skill works

You provide a relative path under scenarios/<world_name>/fs (or leave root) and a regex pattern. The skill walks files (optionally recursively), applies the pattern with optional case-insensitivity, and captures match snippets with configurable context lines. Matches are converted into Note objects and grouped into a collection; the collection ID is returned on success.

When to use it

Locate TODOs, FIXMEs, or technical debt comments across a scenario filesystem.
Extract error messages or log snippets for debugging scenarios.
Audit scenario files for sensitive strings or forbidden patterns.
Collect examples of a pattern across many files for review or reporting.
Quickly search a specific subdirectory in a scenario without cloning the whole world.

Best practices

Provide a focused path to limit scanning time and noise.
Use specific regex patterns to avoid irrelevant matches.
Set context lines to capture meaningful surrounding text for each match.
Limit max_matches to a reasonable number (default 20) for concise results.
Enable case_insensitive when pattern case may vary across files.

Example use cases

Find all occurrences of "TODO" in the src folder to create a task list.
Search for the word "error" with two context lines to gather debugging snippets.
Scan a configuration directory for API keys or other sensitive tokens using a regex.
Collect all instances of a deprecated function name before performing a bulk refactor.

FAQ

What does the skill return?

It returns a collection ID (resource_id) that groups Note objects containing each match snippet and file context.

Can I search non-recursively?

Yes — set recursive to false to restrict the search to the specified directory only.

How do I control the number of results?

Use max_matches to cap returned matches. The default is 20 to keep results manageable.