home / skills / bdambrosio / cognitive_workbench / text-find

text-find skill

safe

This skill locates patterns or substrings in text and returns matches with positions and surrounding context for easy analysis.

npx playbooks add skill bdambrosio/cognitive_workbench --skill text-find

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

Files (1)

Skill.md

1.2 KB

---
name: text-find
type: prompt_augmentation
description: "Locate pattern or substring and return position with context. Use to search for specific substring or pattern in a text document"
---

# text-find

Locate patterns or substrings in text and return matches with context.

## Input

- `target`: Note ID or variable containing text to search
- `pattern`: Text string or regex pattern to find (required)
- `context_lines`: Number of lines before/after to include (optional, default: 1)

## Output

Returns Note containing match results:
- Match positions (line and character)
- Matched text
- Surrounding context
- Count of matches

Returns null if no matches found.

## Behavior

- Case-sensitive by default
- Supports standard regex syntax
- Returns all matches, not just first
- Context helps understand match relevance

## Planning Notes

- Use simple text search for exact substring matching
- Use regex patterns for flexible pattern matching (e.g., email addresses, dates)

## Examples

Simple text search:
```json
{"type":"text-find","target":"$document","pattern":"TODO","out":"$todo_locations"}
```

Pattern search with context:
```json
{"type":"text-find","target":"$log","pattern":"ERROR.*timeout","context_lines":3,"out":"$errors"}
```

Overview

This skill locates a substring or regex pattern inside a text source and returns every match with surrounding context. It reports match positions, the matched text, and configurable lines of context so you can quickly assess relevance. Results are returned as a Note containing match count and detailed entries for each occurrence.

How this skill works

Provide a target text (note ID or variable) and a pattern string or regular expression. The skill performs a case-sensitive search by default, supports standard regex syntax, and finds all matches rather than stopping at the first. For each match it records the line and character position, extracts the matched text, and includes the requested number of lines before and after as context. If no matches are found it returns null.

When to use it

Locate all occurrences of a keyword or phrase inside a document
Extract pattern-based items like emails, dates, or log error signatures
Quickly map where TODOs or FIXMEs appear across notes
Review surrounding lines to verify that a match is relevant before action

Best practices

Use exact substring search for simple literal queries to maximize speed
Use regex when you need flexible matching (capture groups, optional parts, character classes)
Set context_lines to 0 when you only need positions and matched text
Test regex patterns on small excerpts before running across large documents
Remember searches are case-sensitive by default; normalize case first if needed

Example use cases

Find every occurrence of the word TODO across a project and export positions to a task tracker
Scan server logs for ERROR.*timeout and include 3 lines of surrounding log for diagnosis
Extract all email addresses from a dataset using a regex pattern and count unique results
Locate dates in varying formats to prepare a timeline or migration plan

FAQ

Does the skill support regular expressions?

Yes. It accepts standard regex syntax and returns all regex matches.

What happens if nothing matches?

The skill returns null to indicate no matches were found.